mirror of
https://github.com/fish-shell/fish-shell
synced 2024-12-27 05:13:10 +00:00
Convert Markdown files to RST
We use sphinx with rst for our documentation, and github supports rst here, so it seems weird to have markdown just for these. It also allows us e.g. to include the CHANGELOG in the docs without requiring another build dependency.
This commit is contained in:
Fabian Homborg
parent
bc756a981e
commit
e6f5c78d39
6 changed files with 3414 additions and 1807 deletions
1309
CHANGELOG.md
1309
CHANGELOG.md
File diff suppressed because it is too large
Load diff
2677
CHANGELOG.rst
Normal file
2677
CHANGELOG.rst
Normal file
File diff suppressed because it is too large
Load diff
338
CONTRIBUTING.md
338
CONTRIBUTING.md
|
|
@ -1,338 +0,0 @@
|
||||||
# Guidelines For Developers
|
|
||||||
|
|
||||||
This document provides guidelines for making changes to the fish-shell project. This includes rules for how to format the code, naming conventions, et cetera. Generally known as the style of the code. It also includes recommended best practices such as creating a Travis CI account so you can verify that your changes pass all the tests before making a pull request.
|
|
||||||
|
|
||||||
See the bottom of this document for help on installing the linting and style reformatting tools discussed in the following sections.
|
|
||||||
|
|
||||||
Fish source should limit the C++ features it uses to those available in C++11. It should not use exceptions.
|
|
||||||
|
|
||||||
Before introducing a new dependency, please make it optional with graceful failure if possible. Add
|
|
||||||
any new dependencies to the README.md under the *Running* and/or *Building* sections.
|
|
||||||
|
|
||||||
## Versioning
|
|
||||||
|
|
||||||
The fish version is constructed by the *build_tools/git_version_gen.sh* script. For developers the version is the branch name plus the output of `git describe --always --dirty`. Normally the main part of the version will be the closest annotated tag. Which itself is usually the most recent release number (e.g., `2.6.0`).
|
|
||||||
|
|
||||||
## Include What You Use
|
|
||||||
|
|
||||||
You should not depend on symbols being visible to a `*.cpp` module from `#include` statements inside another header file. In other words if your module does `#include "common.h"` and that header does `#include "signal.h"` your module should not assume the sub-include is present. It should instead directly `#include "signal.h"` if it needs any symbol from that header. That makes the actual dependencies much clearer. It also makes it easy to modify the headers included by a specific header file without having to worry that will break any module (or header) that includes a particular header.
|
|
||||||
|
|
||||||
To help enforce this rule the `make lint` (and `make lint-all`) command will run the [include-what-you-use](https://include-what-you-use.org/) tool. You can find the IWYU project on [github](https://github.com/include-what-you-use/include-what-you-use).
|
|
||||||
|
|
||||||
To install the tool on OS X you'll need to add a [formula](https://github.com/jasonmp85/homebrew-iwyu) then install it:
|
|
||||||
|
|
||||||
```
|
|
||||||
brew tap jasonmp85/iwyu
|
|
||||||
brew install iwyu
|
|
||||||
```
|
|
||||||
|
|
||||||
On Ubuntu you can install it via `apt-get`:
|
|
||||||
|
|
||||||
```
|
|
||||||
sudo apt-get install iwyu
|
|
||||||
```
|
|
||||||
|
|
||||||
## Lint Free Code
|
|
||||||
|
|
||||||
Automated analysis tools like cppcheck and oclint can point out potential bugs or code that is extremely hard to understand. They also help ensure the code has a consistent style and that it avoids patterns that tend to confuse people.
|
|
||||||
|
|
||||||
Ultimately we want lint free code. However, at the moment a lot of cleanup is required to reach that goal. For now simply try to avoid introducing new lint.
|
|
||||||
|
|
||||||
To make linting the code easy there are two make targets: `lint` and `lint-all`. The latter does exactly what the name implies. The former will lint any modified but not committed `*.cpp` files. If there is no uncommitted work it will lint the files in the most recent commit.
|
|
||||||
|
|
||||||
Fish has custom cppcheck rules in the file `.cppcheck.rule`. These help catch mistakes such as using `wcwidth()` rather than `fish_wcwidth()`. Please add a new rule if you find similar mistakes being made.
|
|
||||||
|
|
||||||
Fish also depends on `diff` and `expect` for its tests.
|
|
||||||
|
|
||||||
### Dealing With Lint Warnings
|
|
||||||
|
|
||||||
You are strongly encouraged to address a lint warning by refactoring the code, changing variable names, or whatever action is implied by the warning.
|
|
||||||
|
|
||||||
### Suppressing Lint Warnings
|
|
||||||
|
|
||||||
Once in a while the lint tools emit a false positive warning. For example, cppcheck might suggest a memory leak is present when that is not the case. To suppress that cppcheck warning you should insert a line like the following immediately prior to the line cppcheck warned about:
|
|
||||||
|
|
||||||
```
|
|
||||||
// cppcheck-suppress memleak // addr not really leaked
|
|
||||||
```
|
|
||||||
|
|
||||||
The explanatory portion of the suppression comment is optional. For other types of warnings replace "memleak" with the value inside the parenthesis (e.g., "nullPointerRedundantCheck") from a warning like the following:
|
|
||||||
|
|
||||||
```
|
|
||||||
[src/complete.cpp:1727]: warning (nullPointerRedundantCheck): Either the condition 'cmd_node' is redundant or there is possible null pointer dereference: cmd_node.
|
|
||||||
```
|
|
||||||
|
|
||||||
Suppressing oclint warnings is more complicated to describe so I'll refer you to the [OCLint HowTo](http://docs.oclint.org/en/latest/howto/suppress.html#annotations) on the topic.
|
|
||||||
|
|
||||||
## Ensuring Your Changes Conform to the Style Guides
|
|
||||||
|
|
||||||
The following sections discuss the specific rules for the style that should be used when writing fish code. To ensure your changes conform to the style rules you simply need to run
|
|
||||||
|
|
||||||
```
|
|
||||||
build_tools/style.fish
|
|
||||||
```
|
|
||||||
|
|
||||||
before committing your change. That will run `git-clang-format` to rewrite only the lines you're modifying.
|
|
||||||
|
|
||||||
If you've already committed your changes that's okay since it will then check the files in the most recent commit. This can be useful after you've merged another person's change and want to check that it's style is acceptable. However, in that case it will run `clang-format` to ensure the entire file, not just the lines modified by the commit, conform to the style.
|
|
||||||
|
|
||||||
If you want to check the style of the entire code base run
|
|
||||||
|
|
||||||
```
|
|
||||||
build_tools/style.fish --all
|
|
||||||
```
|
|
||||||
|
|
||||||
That command will refuse to restyle any files if you have uncommitted changes.
|
|
||||||
|
|
||||||
### Configuring Your Editor for Fish C++ Code
|
|
||||||
|
|
||||||
#### ViM
|
|
||||||
|
|
||||||
As of ViM 7.4 it does not recognize triple-slash comments as used by Doxygen and the OS X Xcode IDE to flag comments that explain the following C symbol. This means the `gq` key binding to reformat such comments doesn't behave as expected. You can fix that by adding the following to your vimrc:
|
|
||||||
|
|
||||||
```
|
|
||||||
autocmd Filetype c,cpp setlocal comments^=:///
|
|
||||||
```
|
|
||||||
|
|
||||||
If you use ViM I recommend the [vim-clang-format plugin](https://github.com/rhysd/vim-clang-format) by [@rhysd](https://github.com/rhysd).
|
|
||||||
|
|
||||||
You can also get ViM to provide reasonably correct behavior by installing
|
|
||||||
|
|
||||||
http://www.vim.org/scripts/script.php?script_id=2636
|
|
||||||
|
|
||||||
#### Emacs
|
|
||||||
|
|
||||||
If you use Emacs: TBD
|
|
||||||
|
|
||||||
### Configuring Your Editor for Fish Scripts
|
|
||||||
|
|
||||||
If you use ViM: Install [vim-fish](https://github.com/dag/vim-fish), make sure you have syntax and filetype functionality in `~/.vimrc`:
|
|
||||||
|
|
||||||
```
|
|
||||||
syntax enable
|
|
||||||
filetype plugin indent on
|
|
||||||
```
|
|
||||||
|
|
||||||
Then turn on some options for nicer display of fish scripts in `~/.vim/ftplugin/fish.vim`:
|
|
||||||
|
|
||||||
```
|
|
||||||
" Set up :make to use fish for syntax checking.
|
|
||||||
compiler fish
|
|
||||||
|
|
||||||
" Set this to have long lines wrap inside comments.
|
|
||||||
setlocal textwidth=79
|
|
||||||
|
|
||||||
" Enable folding of block structures in fish.
|
|
||||||
setlocal foldmethod=expr
|
|
||||||
```
|
|
||||||
|
|
||||||
If you use Emacs: Install [fish-mode](https://github.com/wwwjfy/emacs-fish) (also available in melpa and melpa-stable) and `(setq-default indent-tabs-mode nil)` for it (via a hook or in `use-package`s ":init" block). It can also be made to run fish_indent via e.g.
|
|
||||||
|
|
||||||
```elisp
|
|
||||||
(add-hook 'fish-mode-hook (lambda ()
|
|
||||||
(add-hook 'before-save-hook 'fish_indent-before-save)))
|
|
||||||
```
|
|
||||||
|
|
||||||
### Suppressing Reformatting of C++ Code
|
|
||||||
|
|
||||||
If you have a good reason for doing so you can tell `clang-format` to not reformat a block of code by enclosing it in comments like this:
|
|
||||||
|
|
||||||
```
|
|
||||||
// clang-format off
|
|
||||||
code to ignore
|
|
||||||
// clang-format on
|
|
||||||
```
|
|
||||||
|
|
||||||
However, as I write this there are no places in the code where we use this and I can't think of any legitimate reasons for exempting blocks of code from clang-format.
|
|
||||||
|
|
||||||
## Fish Script Style Guide
|
|
||||||
|
|
||||||
1. All fish scripts, such as those in the *share/functions* and *tests* directories, should be formatted using the `fish_indent` command.
|
|
||||||
|
|
||||||
1. Function names should be in all lowercase with words separated by underscores. Private functions should begin with an underscore. The first word should be `fish` if the function is unique to fish.
|
|
||||||
|
|
||||||
1. The first word of global variable names should generally be `fish` for public vars or `_fish` for private vars to minimize the possibility of name clashes with user defined vars.
|
|
||||||
|
|
||||||
## C++ Style Guide
|
|
||||||
|
|
||||||
1. The [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) forms the basis of the fish C++ style guide. There are two major deviations for the fish project. First, a four, rather than two, space indent. Second, line lengths up to 100, rather than 80, characters.
|
|
||||||
|
|
||||||
1. The `clang-format` command is authoritative with respect to indentation, whitespace around operators, etc.
|
|
||||||
|
|
||||||
1. All names in code should be `small_snake_case`. No Hungarian notation is used. The names for classes and structs should be followed by `_t`.
|
|
||||||
|
|
||||||
1. Always attach braces to the surrounding context.
|
|
||||||
|
|
||||||
1. Indent with spaces, not tabs and use four spaces per indent.
|
|
||||||
|
|
||||||
1. Document the purpose of a function or class with doxygen-style comment blocks. e.g.:
|
|
||||||
```
|
|
||||||
/**
|
|
||||||
* Sum numbers in a vector.
|
|
||||||
*
|
|
||||||
* @param values Container whose values are summed.
|
|
||||||
* @return sum of `values`, or 0.0 if `values` is empty.
|
|
||||||
*/
|
|
||||||
double sum(std::vector<double> & const values) {
|
|
||||||
...
|
|
||||||
}
|
|
||||||
*/
|
|
||||||
```
|
|
||||||
or
|
|
||||||
```
|
|
||||||
/// brief description of somefunction()
|
|
||||||
void somefunction() {
|
|
||||||
```
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
The source code for fish includes a large collection of tests. If you are making any changes to fish, running these tests is mandatory to make sure the behaviour remains consistent and regressions are not introduced. Even if you don't run the tests on your machine, they will still be run via the [Travis CI](https://travis-ci.org/fish-shell/fish-shell) service.
|
|
||||||
|
|
||||||
You are strongly encouraged to add tests when changing the functionality of fish, especially if you are fixing a bug to help ensure there are no regressions in the future (i.e., we don't reintroduce the bug).
|
|
||||||
|
|
||||||
### Local testing
|
|
||||||
|
|
||||||
The tests can be run on your local computer on all operating systems.
|
|
||||||
|
|
||||||
```
|
|
||||||
cmake path/to/fish-shell
|
|
||||||
make test
|
|
||||||
```
|
|
||||||
|
|
||||||
### Travis CI Build and Test
|
|
||||||
|
|
||||||
The Travis Continuous Integration services can be used to test your changes using multiple configurations. This is the same service that the fish-shell project uses to ensure new changes haven't broken anything. Thus it is a really good idea that you leverage Travis CI before making a pull request to avoid potential embarrassment at breaking the build.
|
|
||||||
|
|
||||||
You will need to [fork the fish-shell repository on GitHub](https://help.github.com/articles/fork-a-repo/), then setup Travis to test your changes before making a pull request.
|
|
||||||
|
|
||||||
1. [Sign in to Travis CI](https://travis-ci.org/auth) with your GitHub account, accepting the GitHub access permissions confirmation.
|
|
||||||
1. Once you're signed in and your repositories are synchronized, go to your [profile page](https://travis-ci.org/profile) and enable the fish-shell repository.
|
|
||||||
1. Push your changes to GitHub.
|
|
||||||
|
|
||||||
You'll receive an email when the tests are complete telling you whether or not any tests failed.
|
|
||||||
|
|
||||||
You'll find the configuration used to control Travis in the `.travis.yml` file.
|
|
||||||
|
|
||||||
### Git hooks
|
|
||||||
|
|
||||||
Since developers sometimes forget to run the tests, it can be helpful to use git hooks (see githooks(5)) to automate it.
|
|
||||||
|
|
||||||
One possibility is a pre-push hook script like this one:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
#!/bin/sh
|
|
||||||
#### A pre-push hook for the fish-shell project
|
|
||||||
# This will run the tests when a push to master is detected, and will stop that if the tests fail
|
|
||||||
# Save this as .git/hooks/pre-push and make it executable
|
|
||||||
|
|
||||||
protected_branch='master'
|
|
||||||
|
|
||||||
# Git gives us lines like "refs/heads/frombranch SOMESHA1 refs/heads/tobranch SOMESHA1"
|
|
||||||
# We're only interested in the branches
|
|
||||||
while read from _ to _; do
|
|
||||||
if [ "x$to" = "xrefs/heads/$protected_branch" ]; then
|
|
||||||
isprotected=1
|
|
||||||
fi
|
|
||||||
done
|
|
||||||
if [ "x$isprotected" = x1 ]; then
|
|
||||||
echo "Running tests before push to master"
|
|
||||||
make test
|
|
||||||
RESULT=$?
|
|
||||||
if [ $RESULT -ne 0 ]; then
|
|
||||||
echo "Tests failed for a push to master, we can't let you do that" >&2
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
fi
|
|
||||||
exit 0
|
|
||||||
```
|
|
||||||
|
|
||||||
This will check if the push is to the master branch and, if it is, only allow the push if running `make test` succeeds. In some circumstances it may be advisable to circumvent this check with `git push --no-verify`, but usually that isn't necessary.
|
|
||||||
|
|
||||||
To install the hook, place the code in a new file `.git/hooks/pre-push` and make it executable.
|
|
||||||
|
|
||||||
### Coverity Scan
|
|
||||||
|
|
||||||
We use Coverity's static analysis tool which offers free access to open source projects. While access to the tool itself is restricted, fish-shell organization members should know that they can login [here](https://scan.coverity.com/projects/fish-shell-fish-shell?tab=overview) with their GitHub account. Currently, tests are triggered upon merging the `master` branch into `coverity_scan_master`. Even if you are not a fish developer, you can keep an eye on our statistics there.
|
|
||||||
|
|
||||||
## Installing the Required Tools
|
|
||||||
|
|
||||||
### Installing the Linting Tools
|
|
||||||
|
|
||||||
To install the lint checkers on Mac OS X using Homebrew:
|
|
||||||
|
|
||||||
```
|
|
||||||
brew tap oclint/formulae
|
|
||||||
brew install oclint
|
|
||||||
brew install cppcheck
|
|
||||||
```
|
|
||||||
|
|
||||||
To install the lint checkers on Debian-based Linux distributions:
|
|
||||||
|
|
||||||
```
|
|
||||||
sudo apt-get install clang
|
|
||||||
sudo apt-get install oclint
|
|
||||||
sudo apt-get install cppcheck
|
|
||||||
```
|
|
||||||
|
|
||||||
### Installing the Reformatting Tools
|
|
||||||
|
|
||||||
Mac OS X:
|
|
||||||
|
|
||||||
```
|
|
||||||
brew install clang-format
|
|
||||||
```
|
|
||||||
|
|
||||||
Debian-based:
|
|
||||||
|
|
||||||
```
|
|
||||||
apt-cache search clang-format
|
|
||||||
```
|
|
||||||
|
|
||||||
Above will list all the versions available. Pick the newest one available (3.9 for Ubuntu 16.10 as I write this) and install it:
|
|
||||||
|
|
||||||
```
|
|
||||||
sudo apt-get install clang-format-3.9
|
|
||||||
sudo ln -s /usr/bin/clang-format-3.9 /usr/bin/clang-format
|
|
||||||
```
|
|
||||||
|
|
||||||
## Message Translations
|
|
||||||
|
|
||||||
Fish uses the GNU gettext library to translate messages from English to other languages.
|
|
||||||
|
|
||||||
All non-debug messages output for user consumption should be marked for translation. In C++, this requires the use of the `_` (underscore) macro:
|
|
||||||
|
|
||||||
```
|
|
||||||
streams.out.append_format(_(L"%ls: There are no jobs\n"), argv[0]);
|
|
||||||
```
|
|
||||||
|
|
||||||
All messages in fish script must be enclosed in single or double quote characters. They must also be translated via a subcommand. This means that the following are **not** valid:
|
|
||||||
|
|
||||||
```
|
|
||||||
echo (_ hello)
|
|
||||||
_ "goodbye"
|
|
||||||
```
|
|
||||||
|
|
||||||
Above should be written like this instead:
|
|
||||||
|
|
||||||
```
|
|
||||||
echo (_ "hello")
|
|
||||||
echo (_ "goodbye")
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that you can use either single or double quotes to enclose the message to be translated. You can also optionally include spaces after the opening parentheses and once again before the closing parentheses.
|
|
||||||
|
|
||||||
Creating and updating translations requires the Gettext tools, including `xgettext`, `msgfmt` and `msgmerge`. Translation sources are stored in the `po` directory, named `LANG.po`, where `LANG` is the two letter ISO 639-1 language code of the target language (eg `de` for German).
|
|
||||||
|
|
||||||
To create a new translation, for example for German:
|
|
||||||
* generate a `messages.pot` file by running `build_tools/fish_xgettext.fish` from the source tree
|
|
||||||
* copy `messages.pot` to `po/LANG.po` ()
|
|
||||||
|
|
||||||
To update a translation:
|
|
||||||
* generate a `messages.pot` file by running `build_tools/fish_xgettext.fish` from the source tree
|
|
||||||
* update the existing translation by running `msgmerge --update --no-fuzzy-matching po/LANG.po messages.pot`
|
|
||||||
|
|
||||||
Many tools are available for editing translation files, including command-line and graphical user interface programs.
|
|
||||||
|
|
||||||
Be cautious about blindly updating an existing translation file. Trivial changes to an existing message (eg changing the punctuation) will cause existing translations to be removed, since the tools do literal string matching. Therefore, in general, you need to carefully review any recommended deletions.
|
|
||||||
|
|
||||||
Read the [translations wiki](https://github.com/fish-shell/fish-shell/wiki/Translations) for more information.
|
|
||||||
499
CONTRIBUTING.rst
Normal file
499
CONTRIBUTING.rst
Normal file
|
|
@ -0,0 +1,499 @@
|
||||||
|
Guidelines For Developers
|
||||||
|
=========================
|
||||||
|
|
||||||
|
This document provides guidelines for making changes to the fish-shell
|
||||||
|
project. This includes rules for how to format the code, naming
|
||||||
|
conventions, et cetera. Generally known as the style of the code. It
|
||||||
|
also includes recommended best practices such as creating a Travis CI
|
||||||
|
account so you can verify that your changes pass all the tests before
|
||||||
|
making a pull request.
|
||||||
|
|
||||||
|
See the bottom of this document for help on installing the linting and
|
||||||
|
style reformatting tools discussed in the following sections.
|
||||||
|
|
||||||
|
Fish source should limit the C++ features it uses to those available in
|
||||||
|
C++11. It should not use exceptions.
|
||||||
|
|
||||||
|
Before introducing a new dependency, please make it optional with
|
||||||
|
graceful failure if possible. Add any new dependencies to the README.md
|
||||||
|
under the *Running* and/or *Building* sections.
|
||||||
|
|
||||||
|
Versioning
|
||||||
|
----------
|
||||||
|
|
||||||
|
The fish version is constructed by the *build_tools/git_version_gen.sh*
|
||||||
|
script. For developers the version is the branch name plus the output of
|
||||||
|
``git describe --always --dirty``. Normally the main part of the version
|
||||||
|
will be the closest annotated tag. Which itself is usually the most
|
||||||
|
recent release number (e.g., ``2.6.0``).
|
||||||
|
|
||||||
|
Include What You Use
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
You should not depend on symbols being visible to a ``*.cpp`` module
|
||||||
|
from ``#include`` statements inside another header file. In other words
|
||||||
|
if your module does ``#include "common.h"`` and that header does
|
||||||
|
``#include "signal.h"`` your module should not assume the sub-include is
|
||||||
|
present. It should instead directly ``#include "signal.h"`` if it needs
|
||||||
|
any symbol from that header. That makes the actual dependencies much
|
||||||
|
clearer. It also makes it easy to modify the headers included by a
|
||||||
|
specific header file without having to worry that will break any module
|
||||||
|
(or header) that includes a particular header.
|
||||||
|
|
||||||
|
To help enforce this rule the ``make lint`` (and ``make lint-all``)
|
||||||
|
command will run the
|
||||||
|
`include-what-you-use <https://include-what-you-use.org/>`__ tool. You
|
||||||
|
can find the IWYU project on
|
||||||
|
`github <https://github.com/include-what-you-use/include-what-you-use>`__.
|
||||||
|
|
||||||
|
To install the tool on OS X you’ll need to add a
|
||||||
|
`formula <https://github.com/jasonmp85/homebrew-iwyu>`__ then install
|
||||||
|
it:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
brew tap jasonmp85/iwyu
|
||||||
|
brew install iwyu
|
||||||
|
|
||||||
|
On Ubuntu you can install it via ``apt-get``:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
sudo apt-get install iwyu
|
||||||
|
|
||||||
|
Lint Free Code
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Automated analysis tools like cppcheck and oclint can point out
|
||||||
|
potential bugs or code that is extremely hard to understand. They also
|
||||||
|
help ensure the code has a consistent style and that it avoids patterns
|
||||||
|
that tend to confuse people.
|
||||||
|
|
||||||
|
Ultimately we want lint free code. However, at the moment a lot of
|
||||||
|
cleanup is required to reach that goal. For now simply try to avoid
|
||||||
|
introducing new lint.
|
||||||
|
|
||||||
|
To make linting the code easy there are two make targets: ``lint`` and
|
||||||
|
``lint-all``. The latter does exactly what the name implies. The former
|
||||||
|
will lint any modified but not committed ``*.cpp`` files. If there is no
|
||||||
|
uncommitted work it will lint the files in the most recent commit.
|
||||||
|
|
||||||
|
Fish has custom cppcheck rules in the file ``.cppcheck.rule``. These
|
||||||
|
help catch mistakes such as using ``wcwidth()`` rather than
|
||||||
|
``fish_wcwidth()``. Please add a new rule if you find similar mistakes
|
||||||
|
being made.
|
||||||
|
|
||||||
|
Fish also depends on ``diff`` and ``expect`` for its tests.
|
||||||
|
|
||||||
|
Dealing With Lint Warnings
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
You are strongly encouraged to address a lint warning by refactoring the
|
||||||
|
code, changing variable names, or whatever action is implied by the
|
||||||
|
warning.
|
||||||
|
|
||||||
|
Suppressing Lint Warnings
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Once in a while the lint tools emit a false positive warning. For
|
||||||
|
example, cppcheck might suggest a memory leak is present when that is
|
||||||
|
not the case. To suppress that cppcheck warning you should insert a line
|
||||||
|
like the following immediately prior to the line cppcheck warned about:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
// cppcheck-suppress memleak // addr not really leaked
|
||||||
|
|
||||||
|
The explanatory portion of the suppression comment is optional. For
|
||||||
|
other types of warnings replace “memleak” with the value inside the
|
||||||
|
parenthesis (e.g., “nullPointerRedundantCheck”) from a warning like the
|
||||||
|
following:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
[src/complete.cpp:1727]: warning (nullPointerRedundantCheck): Either the condition 'cmd_node' is redundant or there is possible null pointer dereference: cmd_node.
|
||||||
|
|
||||||
|
Suppressing oclint warnings is more complicated to describe so I’ll
|
||||||
|
refer you to the `OCLint
|
||||||
|
HowTo <http://docs.oclint.org/en/latest/howto/suppress.html#annotations>`__
|
||||||
|
on the topic.
|
||||||
|
|
||||||
|
Ensuring Your Changes Conform to the Style Guides
|
||||||
|
-------------------------------------------------
|
||||||
|
|
||||||
|
The following sections discuss the specific rules for the style that
|
||||||
|
should be used when writing fish code. To ensure your changes conform to
|
||||||
|
the style rules you simply need to run
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
build_tools/style.fish
|
||||||
|
|
||||||
|
before committing your change. That will run ``git-clang-format`` to
|
||||||
|
rewrite only the lines you’re modifying.
|
||||||
|
|
||||||
|
If you’ve already committed your changes that’s okay since it will then
|
||||||
|
check the files in the most recent commit. This can be useful after
|
||||||
|
you’ve merged another person’s change and want to check that it’s style
|
||||||
|
is acceptable. However, in that case it will run ``clang-format`` to
|
||||||
|
ensure the entire file, not just the lines modified by the commit,
|
||||||
|
conform to the style.
|
||||||
|
|
||||||
|
If you want to check the style of the entire code base run
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
build_tools/style.fish --all
|
||||||
|
|
||||||
|
That command will refuse to restyle any files if you have uncommitted
|
||||||
|
changes.
|
||||||
|
|
||||||
|
Configuring Your Editor for Fish C++ Code
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
ViM
|
||||||
|
^^^
|
||||||
|
|
||||||
|
As of ViM 7.4 it does not recognize triple-slash comments as used by
|
||||||
|
Doxygen and the OS X Xcode IDE to flag comments that explain the
|
||||||
|
following C symbol. This means the ``gq`` key binding to reformat such
|
||||||
|
comments doesn’t behave as expected. You can fix that by adding the
|
||||||
|
following to your vimrc:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
autocmd Filetype c,cpp setlocal comments^=:///
|
||||||
|
|
||||||
|
If you use ViM I recommend the `vim-clang-format
|
||||||
|
plugin <https://github.com/rhysd/vim-clang-format>`__ by
|
||||||
|
[@rhysd](https://github.com/rhysd).
|
||||||
|
|
||||||
|
You can also get ViM to provide reasonably correct behavior by
|
||||||
|
installing
|
||||||
|
|
||||||
|
http://www.vim.org/scripts/script.php?script_id=2636
|
||||||
|
|
||||||
|
Emacs
|
||||||
|
^^^^^
|
||||||
|
|
||||||
|
If you use Emacs: TBD
|
||||||
|
|
||||||
|
Configuring Your Editor for Fish Scripts
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
If you use ViM: Install `vim-fish <https://github.com/dag/vim-fish>`__,
|
||||||
|
make sure you have syntax and filetype functionality in ``~/.vimrc``:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
syntax enable
|
||||||
|
filetype plugin indent on
|
||||||
|
|
||||||
|
Then turn on some options for nicer display of fish scripts in
|
||||||
|
``~/.vim/ftplugin/fish.vim``:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
" Set up :make to use fish for syntax checking.
|
||||||
|
compiler fish
|
||||||
|
|
||||||
|
" Set this to have long lines wrap inside comments.
|
||||||
|
setlocal textwidth=79
|
||||||
|
|
||||||
|
" Enable folding of block structures in fish.
|
||||||
|
setlocal foldmethod=expr
|
||||||
|
|
||||||
|
If you use Emacs: Install
|
||||||
|
`fish-mode <https://github.com/wwwjfy/emacs-fish>`__ (also available in
|
||||||
|
melpa and melpa-stable) and ``(setq-default indent-tabs-mode nil)`` for
|
||||||
|
it (via a hook or in ``use-package``\ s “:init” block). It can also be
|
||||||
|
made to run fish_indent via e.g.
|
||||||
|
|
||||||
|
.. code:: elisp
|
||||||
|
|
||||||
|
(add-hook 'fish-mode-hook (lambda ()
|
||||||
|
(add-hook 'before-save-hook 'fish_indent-before-save)))
|
||||||
|
|
||||||
|
Suppressing Reformatting of C++ Code
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
If you have a good reason for doing so you can tell ``clang-format`` to
|
||||||
|
not reformat a block of code by enclosing it in comments like this:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
// clang-format off
|
||||||
|
code to ignore
|
||||||
|
// clang-format on
|
||||||
|
|
||||||
|
However, as I write this there are no places in the code where we use
|
||||||
|
this and I can’t think of any legitimate reasons for exempting blocks of
|
||||||
|
code from clang-format.
|
||||||
|
|
||||||
|
Fish Script Style Guide
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
1. All fish scripts, such as those in the *share/functions* and *tests*
|
||||||
|
directories, should be formatted using the ``fish_indent`` command.
|
||||||
|
|
||||||
|
2. Function names should be in all lowercase with words separated by
|
||||||
|
underscores. Private functions should begin with an underscore. The
|
||||||
|
first word should be ``fish`` if the function is unique to fish.
|
||||||
|
|
||||||
|
3. The first word of global variable names should generally be ``fish``
|
||||||
|
for public vars or ``_fish`` for private vars to minimize the
|
||||||
|
possibility of name clashes with user defined vars.
|
||||||
|
|
||||||
|
C++ Style Guide
|
||||||
|
---------------
|
||||||
|
|
||||||
|
1. The `Google C++ Style
|
||||||
|
Guide <https://google.github.io/styleguide/cppguide.html>`__ forms
|
||||||
|
the basis of the fish C++ style guide. There are two major deviations
|
||||||
|
for the fish project. First, a four, rather than two, space indent.
|
||||||
|
Second, line lengths up to 100, rather than 80, characters.
|
||||||
|
|
||||||
|
2. The ``clang-format`` command is authoritative with respect to
|
||||||
|
indentation, whitespace around operators, etc.
|
||||||
|
|
||||||
|
3. All names in code should be ``small_snake_case``. No Hungarian
|
||||||
|
notation is used. The names for classes and structs should be
|
||||||
|
followed by ``_t``.
|
||||||
|
|
||||||
|
4. Always attach braces to the surrounding context.
|
||||||
|
|
||||||
|
5. Indent with spaces, not tabs and use four spaces per indent.
|
||||||
|
|
||||||
|
6. Document the purpose of a function or class with doxygen-style
|
||||||
|
comment blocks. e.g.:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Sum numbers in a vector.
|
||||||
|
*
|
||||||
|
* @param values Container whose values are summed.
|
||||||
|
* @return sum of `values`, or 0.0 if `values` is empty.
|
||||||
|
*/
|
||||||
|
double sum(std::vector<double> & const values) {
|
||||||
|
...
|
||||||
|
}
|
||||||
|
*/
|
||||||
|
|
||||||
|
or
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
/// brief description of somefunction()
|
||||||
|
void somefunction() {
|
||||||
|
|
||||||
|
Testing
|
||||||
|
-------
|
||||||
|
|
||||||
|
The source code for fish includes a large collection of tests. If you
|
||||||
|
are making any changes to fish, running these tests is mandatory to make
|
||||||
|
sure the behaviour remains consistent and regressions are not
|
||||||
|
introduced. Even if you don’t run the tests on your machine, they will
|
||||||
|
still be run via the `Travis
|
||||||
|
CI <https://travis-ci.org/fish-shell/fish-shell>`__ service.
|
||||||
|
|
||||||
|
You are strongly encouraged to add tests when changing the functionality
|
||||||
|
of fish, especially if you are fixing a bug to help ensure there are no
|
||||||
|
regressions in the future (i.e., we don’t reintroduce the bug).
|
||||||
|
|
||||||
|
Local testing
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The tests can be run on your local computer on all operating systems.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
cmake path/to/fish-shell
|
||||||
|
make test
|
||||||
|
|
||||||
|
Travis CI Build and Test
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The Travis Continuous Integration services can be used to test your
|
||||||
|
changes using multiple configurations. This is the same service that the
|
||||||
|
fish-shell project uses to ensure new changes haven’t broken anything.
|
||||||
|
Thus it is a really good idea that you leverage Travis CI before making
|
||||||
|
a pull request to avoid potential embarrassment at breaking the build.
|
||||||
|
|
||||||
|
You will need to `fork the fish-shell repository on
|
||||||
|
GitHub <https://help.github.com/articles/fork-a-repo/>`__, then setup
|
||||||
|
Travis to test your changes before making a pull request.
|
||||||
|
|
||||||
|
1. `Sign in to Travis CI <https://travis-ci.org/auth>`__ with your
|
||||||
|
GitHub account, accepting the GitHub access permissions confirmation.
|
||||||
|
2. Once you’re signed in and your repositories are synchronized, go to
|
||||||
|
your `profile page <https://travis-ci.org/profile>`__ and enable the
|
||||||
|
fish-shell repository.
|
||||||
|
3. Push your changes to GitHub.
|
||||||
|
|
||||||
|
You’ll receive an email when the tests are complete telling you whether
|
||||||
|
or not any tests failed.
|
||||||
|
|
||||||
|
You’ll find the configuration used to control Travis in the
|
||||||
|
``.travis.yml`` file.
|
||||||
|
|
||||||
|
Git hooks
|
||||||
|
~~~~~~~~~
|
||||||
|
|
||||||
|
Since developers sometimes forget to run the tests, it can be helpful to
|
||||||
|
use git hooks (see githooks(5)) to automate it.
|
||||||
|
|
||||||
|
One possibility is a pre-push hook script like this one:
|
||||||
|
|
||||||
|
.. code:: sh
|
||||||
|
|
||||||
|
#!/bin/sh
|
||||||
|
#### A pre-push hook for the fish-shell project
|
||||||
|
# This will run the tests when a push to master is detected, and will stop that if the tests fail
|
||||||
|
# Save this as .git/hooks/pre-push and make it executable
|
||||||
|
|
||||||
|
protected_branch='master'
|
||||||
|
|
||||||
|
# Git gives us lines like "refs/heads/frombranch SOMESHA1 refs/heads/tobranch SOMESHA1"
|
||||||
|
# We're only interested in the branches
|
||||||
|
while read from _ to _; do
|
||||||
|
if [ "x$to" = "xrefs/heads/$protected_branch" ]; then
|
||||||
|
isprotected=1
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
if [ "x$isprotected" = x1 ]; then
|
||||||
|
echo "Running tests before push to master"
|
||||||
|
make test
|
||||||
|
RESULT=$?
|
||||||
|
if [ $RESULT -ne 0 ]; then
|
||||||
|
echo "Tests failed for a push to master, we can't let you do that" >&2
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
exit 0
|
||||||
|
|
||||||
|
This will check if the push is to the master branch and, if it is, only
|
||||||
|
allow the push if running ``make test`` succeeds. In some circumstances
|
||||||
|
it may be advisable to circumvent this check with
|
||||||
|
``git push --no-verify``, but usually that isn’t necessary.
|
||||||
|
|
||||||
|
To install the hook, place the code in a new file
|
||||||
|
``.git/hooks/pre-push`` and make it executable.
|
||||||
|
|
||||||
|
Coverity Scan
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
We use Coverity’s static analysis tool which offers free access to open
|
||||||
|
source projects. While access to the tool itself is restricted,
|
||||||
|
fish-shell organization members should know that they can login
|
||||||
|
`here <https://scan.coverity.com/projects/fish-shell-fish-shell?tab=overview>`__
|
||||||
|
with their GitHub account. Currently, tests are triggered upon merging
|
||||||
|
the ``master`` branch into ``coverity_scan_master``. Even if you are not
|
||||||
|
a fish developer, you can keep an eye on our statistics there.
|
||||||
|
|
||||||
|
Installing the Required Tools
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
Installing the Linting Tools
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
To install the lint checkers on Mac OS X using Homebrew:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
brew tap oclint/formulae
|
||||||
|
brew install oclint
|
||||||
|
brew install cppcheck
|
||||||
|
|
||||||
|
To install the lint checkers on Debian-based Linux distributions:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
sudo apt-get install clang
|
||||||
|
sudo apt-get install oclint
|
||||||
|
sudo apt-get install cppcheck
|
||||||
|
|
||||||
|
Installing the Reformatting Tools
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Mac OS X:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
brew install clang-format
|
||||||
|
|
||||||
|
Debian-based:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
apt-cache search clang-format
|
||||||
|
|
||||||
|
Above will list all the versions available. Pick the newest one
|
||||||
|
available (3.9 for Ubuntu 16.10 as I write this) and install it:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
sudo apt-get install clang-format-3.9
|
||||||
|
sudo ln -s /usr/bin/clang-format-3.9 /usr/bin/clang-format
|
||||||
|
|
||||||
|
Message Translations
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
Fish uses the GNU gettext library to translate messages from English to
|
||||||
|
other languages.
|
||||||
|
|
||||||
|
All non-debug messages output for user consumption should be marked for
|
||||||
|
translation. In C++, this requires the use of the ``_`` (underscore)
|
||||||
|
macro:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
streams.out.append_format(_(L"%ls: There are no jobs\n"), argv[0]);
|
||||||
|
|
||||||
|
All messages in fish script must be enclosed in single or double quote
|
||||||
|
characters. They must also be translated via a subcommand. This means
|
||||||
|
that the following are **not** valid:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
echo (_ hello)
|
||||||
|
_ "goodbye"
|
||||||
|
|
||||||
|
Above should be written like this instead:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
echo (_ "hello")
|
||||||
|
echo (_ "goodbye")
|
||||||
|
|
||||||
|
Note that you can use either single or double quotes to enclose the
|
||||||
|
message to be translated. You can also optionally include spaces after
|
||||||
|
the opening parentheses and once again before the closing parentheses.
|
||||||
|
|
||||||
|
Creating and updating translations requires the Gettext tools, including
|
||||||
|
``xgettext``, ``msgfmt`` and ``msgmerge``. Translation sources are
|
||||||
|
stored in the ``po`` directory, named ``LANG.po``, where ``LANG`` is the
|
||||||
|
two letter ISO 639-1 language code of the target language (eg ``de`` for
|
||||||
|
German).
|
||||||
|
|
||||||
|
To create a new translation, for example for German: \* generate a
|
||||||
|
``messages.pot`` file by running ``build_tools/fish_xgettext.fish`` from
|
||||||
|
the source tree \* copy ``messages.pot`` to ``po/LANG.po`` ()
|
||||||
|
|
||||||
|
To update a translation: \* generate a ``messages.pot`` file by running
|
||||||
|
``build_tools/fish_xgettext.fish`` from the source tree \* update the
|
||||||
|
existing translation by running
|
||||||
|
``msgmerge --update --no-fuzzy-matching po/LANG.po messages.pot``
|
||||||
|
|
||||||
|
Many tools are available for editing translation files, including
|
||||||
|
command-line and graphical user interface programs.
|
||||||
|
|
||||||
|
Be cautious about blindly updating an existing translation file. Trivial
|
||||||
|
changes to an existing message (eg changing the punctuation) will cause
|
||||||
|
existing translations to be removed, since the tools do literal string
|
||||||
|
matching. Therefore, in general, you need to carefully review any
|
||||||
|
recommended deletions.
|
||||||
|
|
||||||
|
Read the `translations
|
||||||
|
wiki <https://github.com/fish-shell/fish-shell/wiki/Translations>`__ for
|
||||||
|
more information.
|
||||||
160
README.md
160
README.md
|
|
@ -1,160 +0,0 @@
|
||||||
[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 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).
|
|
||||||
|
|
||||||
## 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>
|
|
||||||
|
|
||||||
You can quickly play with fish right in your browser by clicking the button below:
|
|
||||||
|
|
||||||
[](https://rootnroll.com/d/fish-shell/)
|
|
||||||
|
|
||||||
## 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&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
|
|
||||||
sudo apt-get update
|
|
||||||
sudo apt-get install fish
|
|
||||||
```
|
|
||||||
|
|
||||||
Instructions for other distributions may be found at [fishshell.com](https://fishshell.com).
|
|
||||||
|
|
||||||
### Windows
|
|
||||||
|
|
||||||
- On Windows 10, fish can be installed under the WSL Windows Subsystem for Linux with the instructions for the appropriate distribution listed above under "Packages for Linux", or from source with the instructions below.
|
|
||||||
- Fish can also be installed on all versions of Windows using [Cygwin](https://cygwin.com/) (from the **Shells** category).
|
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|
||||||
Running fish requires:
|
|
||||||
|
|
||||||
* curses or ncurses (preinstalled on most \*nix systems)
|
|
||||||
* some common \*nix system utilities (currently `mktemp`), in addition to the basic POSIX utilities (`cat`, `cut`, `dirname`, `ls`, `mkdir`, `mkfifo`, `rm`, `sort`, `tee`, `tr`, `uname` and `sed` at least, but the full coreutils plus find, sed and awk is preferred)
|
|
||||||
* gettext (library and `gettext` command), if compiled with translation support
|
|
||||||
|
|
||||||
The following optional features also have specific requirements:
|
|
||||||
|
|
||||||
* builtin commands that have the `--help` option or print usage messages require `ul` and either `nroff` or `mandoc` for display
|
|
||||||
* automated completion generation from manual pages requires Python (2.7+ or 3.3+) and possibly the
|
|
||||||
`backports.lzma` module for Python 2.7
|
|
||||||
* the `fish_config` web configuration tool requires Python (2.7+ or 3.3 +) and a web browser
|
|
||||||
* 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
|
|
||||||
|
|
||||||
### Switching to fish
|
|
||||||
|
|
||||||
If you wish to use fish as your default shell, use the following command:
|
|
||||||
|
|
||||||
chsh -s /usr/local/bin/fish
|
|
||||||
|
|
||||||
`chsh` will prompt you for your password and change your default shell. (Substitute `/usr/local/bin/fish` with whatever path fish was installed to, if it differs.) Log out, then log in again for the changes to take effect.
|
|
||||||
|
|
||||||
Use the following command if fish isn't already added to `/etc/shells` to permit fish to be your login shell:
|
|
||||||
|
|
||||||
echo /usr/local/bin/fish | sudo tee -a /etc/shells
|
|
||||||
|
|
||||||
To switch your default shell back, you can run `chsh -s /bin/bash` (substituting `/bin/bash` with `/bin/tcsh` or `/bin/zsh` as appropriate).
|
|
||||||
|
|
||||||
## Building
|
|
||||||
|
|
||||||
### Dependencies
|
|
||||||
|
|
||||||
Compiling fish requires:
|
|
||||||
|
|
||||||
* a C++11 compiler (g++ 4.8 or later, or clang 3.3 or later)
|
|
||||||
* CMake (version 3.2 or later)
|
|
||||||
* 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
|
|
||||||
|
|
||||||
Sphinx is also optionally required to build the documentation from a cloned git repository.
|
|
||||||
|
|
||||||
### Building from source (all platforms) - Makefile generator
|
|
||||||
|
|
||||||
To install into `/usr/local`, run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir build; cd build
|
|
||||||
cmake ..
|
|
||||||
make
|
|
||||||
sudo make install
|
|
||||||
```
|
|
||||||
|
|
||||||
The install directory can be changed using the `-DCMAKE_INSTALL_PREFIX` parameter for `cmake`.
|
|
||||||
|
|
||||||
### Building from source (macOS) - Xcode
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir build; cd build
|
|
||||||
cmake .. -G Xcode
|
|
||||||
```
|
|
||||||
|
|
||||||
An Xcode project will now be available in the `build` subdirectory. You can open it with Xcode,
|
|
||||||
or run the following to build and install in `/usr/local`:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
xcodebuild
|
|
||||||
xcodebuild -scheme install
|
|
||||||
```
|
|
||||||
|
|
||||||
The install directory can be changed using the `-DCMAKE_INSTALL_PREFIX` parameter for `cmake`.
|
|
||||||
|
|
||||||
### 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 cmake ncurses-dev libncurses5-dev libpcre2-dev gettext
|
|
||||||
|
|
||||||
On RedHat, CentOS, or Amazon EC2:
|
|
||||||
|
|
||||||
sudo yum install ncurses-devel
|
|
||||||
|
|
||||||
## Contributing Changes to the Code
|
|
||||||
|
|
||||||
See the [Guide for Developers](CONTRIBUTING.md).
|
|
||||||
|
|
||||||
## 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> or join us on our [gitter.im channel](https://gitter.im/fish-shell/fish-shell). Or use the [fish tag on Stackoverflow](https://stackoverflow.com/questions/tagged/fish) for questions related to fish script and the [fish tag on Superuser](https://superuser.com/questions/tagged/fish) for all other questions (e.g., customizing colors, changing key bindings).
|
|
||||||
|
|
||||||
Found a bug? Have an awesome idea? Please [open an issue](https://github.com/fish-shell/fish-shell/issues/new).
|
|
||||||
238
README.rst
Normal file
238
README.rst
Normal file
|
|
@ -0,0 +1,238 @@
|
||||||
|
`fish <https://fishshell.com/>`__ - the friendly interactive shell |Build Status|
|
||||||
|
=================================================================================
|
||||||
|
|
||||||
|
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>`__.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
You can quickly play with fish right in your browser by clicking the
|
||||||
|
button below:
|
||||||
|
|
||||||
|
|Try in browser|
|
||||||
|
|
||||||
|
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&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
|
||||||
|
sudo apt-get update
|
||||||
|
sudo apt-get install fish
|
||||||
|
|
||||||
|
Instructions for other distributions may be found at
|
||||||
|
`fishshell.com <https://fishshell.com>`__.
|
||||||
|
|
||||||
|
Windows
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
- On Windows 10, fish can be installed under the WSL Windows Subsystem
|
||||||
|
for Linux with the instructions for the appropriate distribution
|
||||||
|
listed above under “Packages for Linux”, or from source with the
|
||||||
|
instructions below.
|
||||||
|
- Fish can also be installed on all versions of Windows using
|
||||||
|
`Cygwin <https://cygwin.com/>`__ (from the **Shells** category).
|
||||||
|
|
||||||
|
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
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Running fish requires:
|
||||||
|
|
||||||
|
- curses or ncurses (preinstalled on most \*nix systems)
|
||||||
|
- some common \*nix system utilities (currently ``mktemp``), in
|
||||||
|
addition to the basic POSIX utilities (``cat``, ``cut``, ``dirname``,
|
||||||
|
``ls``, ``mkdir``, ``mkfifo``, ``rm``, ``sort``, ``tee``, ``tr``,
|
||||||
|
``uname`` and ``sed`` at least, but the full coreutils plus find, sed
|
||||||
|
and awk is preferred)
|
||||||
|
- gettext (library and ``gettext`` command), if compiled with
|
||||||
|
translation support
|
||||||
|
|
||||||
|
The following optional features also have specific requirements:
|
||||||
|
|
||||||
|
- builtin commands that have the ``--help`` option or print usage
|
||||||
|
messages require ``ul`` and either ``nroff`` or ``mandoc`` for
|
||||||
|
display
|
||||||
|
- automated completion generation from manual pages requires Python
|
||||||
|
(2.7+ or 3.3+) and possibly the ``backports.lzma`` module for Python
|
||||||
|
2.7
|
||||||
|
- the ``fish_config`` web configuration tool requires Python (2.7+ or
|
||||||
|
3.3 +) and a web browser
|
||||||
|
- 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
|
||||||
|
|
||||||
|
Switching to fish
|
||||||
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
If you wish to use fish as your default shell, use the following
|
||||||
|
command:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
chsh -s /usr/local/bin/fish
|
||||||
|
|
||||||
|
``chsh`` will prompt you for your password and change your default
|
||||||
|
shell. (Substitute ``/usr/local/bin/fish`` with whatever path fish was
|
||||||
|
installed to, if it differs.) Log out, then log in again for the changes
|
||||||
|
to take effect.
|
||||||
|
|
||||||
|
Use the following command if fish isn’t already added to ``/etc/shells``
|
||||||
|
to permit fish to be your login shell:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
echo /usr/local/bin/fish | sudo tee -a /etc/shells
|
||||||
|
|
||||||
|
To switch your default shell back, you can run ``chsh -s /bin/bash``
|
||||||
|
(substituting ``/bin/bash`` with ``/bin/tcsh`` or ``/bin/zsh`` as
|
||||||
|
appropriate).
|
||||||
|
|
||||||
|
Building
|
||||||
|
--------
|
||||||
|
|
||||||
|
.. _dependencies-1:
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Compiling fish requires:
|
||||||
|
|
||||||
|
- a C++11 compiler (g++ 4.8 or later, or clang 3.3 or later)
|
||||||
|
- CMake (version 3.2 or later)
|
||||||
|
- 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
|
||||||
|
|
||||||
|
Sphinx is also optionally required to build the documentation from a
|
||||||
|
cloned git repository.
|
||||||
|
|
||||||
|
Building from source (all platforms) - Makefile generator
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
To install into ``/usr/local``, run:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
mkdir build; cd build
|
||||||
|
cmake ..
|
||||||
|
make
|
||||||
|
sudo make install
|
||||||
|
|
||||||
|
The install directory can be changed using the
|
||||||
|
``-DCMAKE_INSTALL_PREFIX`` parameter for ``cmake``.
|
||||||
|
|
||||||
|
Building from source (macOS) - Xcode
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
mkdir build; cd build
|
||||||
|
cmake .. -G Xcode
|
||||||
|
|
||||||
|
An Xcode project will now be available in the ``build`` subdirectory.
|
||||||
|
You can open it with Xcode, or run the following to build and install in
|
||||||
|
``/usr/local``:
|
||||||
|
|
||||||
|
.. code:: bash
|
||||||
|
|
||||||
|
xcodebuild
|
||||||
|
xcodebuild -scheme install
|
||||||
|
|
||||||
|
The install directory can be changed using the
|
||||||
|
``-DCMAKE_INSTALL_PREFIX`` parameter for ``cmake``.
|
||||||
|
|
||||||
|
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 cmake ncurses-dev libncurses5-dev libpcre2-dev gettext
|
||||||
|
|
||||||
|
On RedHat, CentOS, or Amazon EC2:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
sudo yum install ncurses-devel
|
||||||
|
|
||||||
|
Contributing Changes to the Code
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
See the `Guide for Developers <CONTRIBUTING.md>`__.
|
||||||
|
|
||||||
|
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
|
||||||
|
or join us on our `gitter.im
|
||||||
|
channel <https://gitter.im/fish-shell/fish-shell>`__. Or use the `fish
|
||||||
|
tag on
|
||||||
|
Stackoverflow <https://stackoverflow.com/questions/tagged/fish>`__ for
|
||||||
|
questions related to fish script and the `fish tag on
|
||||||
|
Superuser <https://superuser.com/questions/tagged/fish>`__ for all other
|
||||||
|
questions (e.g., customizing colors, changing key bindings).
|
||||||
|
|
||||||
|
Found a bug? Have an awesome idea? Please `open an
|
||||||
|
issue <https://github.com/fish-shell/fish-shell/issues/new>`__.
|
||||||
|
|
||||||
|
.. |Build Status| image:: https://travis-ci.org/fish-shell/fish-shell.svg?branch=master
|
||||||
|
:target: https://travis-ci.org/fish-shell/fish-shell
|
||||||
|
.. |Try in browser| image:: https://cdn.rawgit.com/rootnroll/library/assets/try.svg
|
||||||
|
:target: https://rootnroll.com/d/fish-shell/
|
||||||
Loading…
Reference in a new issue