github-mirror/fish-shell
github-mirror/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2025-03-15 23:22:53 +08:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

Merge branch 'master' into string-preserve-missing-newline

Browse Source
This commit is contained in:
Fabian Homborg 2022-03-13 11:21:53 +01:00 committed by GitHub
commit 585d1de653
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
429 changed files with 6269 additions and 3287 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.editorconfig
View File

@ -20,3 +20,9 @@ indent_size = 2
[Dockerfile]
indent_size = 2
[share/{completions,functions}/**.fish]
max_line_length = none
[COMMIT_EDITMSG]
max_line_length = 80

8
.gitattributes vendored
View File

@ -21,11 +21,13 @@
/.github/* export-ignore
/.builds export-ignore
/.builds/* export-ignore
/.travis.yml export-ignore
# for linguist; let github identify our project as C++ instead of C due to pcre2
pcre2/* linguist-vendored
pcre2/** linguist-vendored
angular.js linguist-vendored
doc_src/* linguist-documentation
angular-*.js linguist-vendored
doc_src/** linguist-documentation
*.fish linguist-language=fish
src/*.h linguist-language=c++
src/builtins/*.h linguist-language=c++
share/completions/*.fish linguist-documentation

2
.github/ISSUE_TEMPLATE.md vendored
View File

@ -12,3 +12,5 @@ Please tell us if you tried fish without third-party customizations by executing
Tell us how to reproduce the problem. Including an asciinema.org recording is useful for problems that involve the visual display of fish output such as its prompt.
-->
**YOUR TEXT HERE**

43
.github/workflows/codeql-analysis.yml vendored Normal file
View File

@ -0,0 +1,43 @@
name: "CodeQL"
on:
push:
branches: [ master ]
schedule:
- cron: '18 22 * * 2'
jobs:
analyze:
name: Analyze
runs-on: ubuntu-latest
permissions:
actions: read
contents: read
security-events: write
strategy:
fail-fast: true
matrix:
language: [ 'cpp', 'javascript', 'python' ]
steps:
- name: Checkout repository
uses: actions/checkout@v2
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@v1
with:
languages: ${{ matrix.language }}
# If you wish to specify custom queries, you can do so here or in a config file.
# By default, queries listed here will override any specified in a config file.
# Prefix the list here with "+" to use these queries and those in the config file.
# queries: ./path/to/local/query, your-org/your-repo/queries@main
# Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
# If this step fails, then you should remove it and run the build manually (see below)
- name: Autobuild
uses: github/codeql-action/autobuild@v1
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v1

3
.github/workflows/main.yml vendored
View File

@ -1,9 +1,10 @@
name: Test
name: make test
on: [push, pull_request]
env:
CTEST_PARALLEL_LEVEL: "1"
CMAKE_BUILD_PARALLEL_LEVEL: "4"
jobs:
ubuntu:

155
CHANGELOG.rst
View File

@ -1,5 +1,5 @@
fish 3.4.0 (released ???)
=========================
fish 3.4.0 (released March 12, 2022)
====================================
Notable improvements and fixes
------------------------------
@ -16,8 +16,8 @@ Notable improvements and fixes
foo $(bar)
# this will still split on newlines only.
- Complimenting the ``prompt`` command in 3.3.0, ``fish_config`` gained a ``theme`` subcommand to show and pick from the sample themes (meaning color schemes) directly in the terminal, instead of having to open a webbrowser. For example ``fish_config theme choose Nord`` loads the Nord theme in the current session (:issue:`8132`). The current theme can be saved with ``fish_config theme dump`` and custom themes can be added by saving them in ``~/.config/fish/themes/``.
- ``set`` learned a new option ``--function`` to set a variable in the function's top scope. This should be a more familiar way of scoping variables and avoids issues with ``--local``, which is actually block-scoped (:issue:`565`, :issue:`8145`)::
- Complementing the ``prompt`` command in 3.3.0, ``fish_config`` gained a ``theme`` subcommand to show and pick from the sample themes (meaning color schemes) directly in the terminal, instead of having to open a Web browser. For example ``fish_config theme choose Nord`` loads the Nord theme in the current session (:issue:`8132`). The current theme can be saved with ``fish_config theme dump``, and custom themes can be added by saving them in ``~/.config/fish/themes/``.
- ``set`` and ``read`` learned a new option, ``--function``, to set a variable in the function's top scope. This should be a more familiar way of scoping variables and avoids issues with ``--local``, which is actually block-scoped (:issue:`565`, :issue:`8145`)::
function demonstration
if true
@ -33,8 +33,9 @@ Notable improvements and fixes
> string length --visible (set_color red)foo
3
- Performance improvements to globbing, especially on systems using glibc (by avoiding its slow iswalnum() function). In some cases (large directories with files with many numbers in the names) this almost doubles performance.
- Autosuggestions can now be turned off by setting ``$fish_autosuggestion_enabled`` to 0, and (almost) all highlighting can be turned off by choosing the new "None" theme. The exception is necessary colors, e.g. to distinguish autosuggestions from the actual commandline. (:issue:`8376`)
- Performance improvements to globbing, especially on systems using glibc. In some cases (large directories with files with many numbers in the names) this almost halves the time taken to expand the glob.
- Autosuggestions can now be turned off by setting ``$fish_autosuggestion_enabled`` to 0, and (almost) all highlighting can be turned off by choosing the new "None" theme. The exception is necessary colors, like those which distinguish autosuggestions from the actual command line. (:issue:`8376`)
- The ``fish_git_prompt`` function, which is included in the default prompts, now overrides ``git`` to avoid running commands set by per-repository configuration. This avoids a potential security issue in some circumstances, and has been assigned CVE-2022-20001 (:issue:`8589`).
Deprecations and removed features
---------------------------------
@ -45,10 +46,15 @@ Deprecations and removed features
# with both ampersand-nobg-in-token and qmark-noglob, this argument has no special characters anymore
> open https://www.youtube.com/watch?v=dQw4w9WgXcQ&feature=youtu.be
As a reminder, feature flags can be set on startup with ``fish --features ampersand-nobg-in-token,qmark-noglob`` or with a universal variable called ``fish_features``::
> set -Ua fish_features ampersand-nobg-in-token
- ``$status`` is now forbidden as a command, to prevent a surprisingly common error among new users: Running ``if $status`` (:issue:`8171`). This applies *only* to ``$status``, other variables are still allowed.
- ``set --query`` now returns a falsy status of 255 if given no variable names. This means ``if set -q $foo`` will not enter the if-block if ``$foo`` is empty or unset. To restore the previous behavior you would use something like ``if not set -q foo; or set -q $foo``. We do not expect anyone to have used this on purpose, any places this happens are almost certainly buggy (:issue:`8214`).
- Mac OS X 10.9 is no longer supported. The minimum Mac version is now 10.10 "Yosemite."
- ``set --query`` now returns an exit status of 255 if given no variable names. This means ``if set -q $foo`` will not enter the if-block if ``$foo`` is empty or unset. To restore the previous behavior, use ``if not set -q foo; or set -q $foo`` - but this is unlikely to be desireable (:issue:`8214`).
- ``_`` is now a reserved keyword (:issue:`8342`).
- The special input functions ``delete-or-exit``, ``nextd-or-forward-word`` and ``prevd-or-backward-word`` replace fish functions of the same names (:issue:`8538`).
- Mac OS X 10.9 is no longer supported. The minimum Mac version is now 10.10 "Yosemite."
Scripting improvements
----------------------
@ -61,43 +67,70 @@ Scripting improvements
'blue '
- ``$fish_user_paths`` is now automatically deduplicated to fix a common user error of appending to it in config.fish when it is universal (:issue:`8117`). :ref:`fish_add_path <cmd-fish_add_path>` remains the recommended way to add to $PATH.
- ``return`` can now be used outside of functions. In scripts it does the same thing as :program:`cmd`, in the commandline it sets ``$status`` without exiting (:issue:`8148`).
- An oversight prevented all syntax checks from running on commands given to ``fish -c`` (:issue:`8171`). This includes checks like e.g. ``exec`` not being allowed in a pipeline and ``$$`` not being a valid variable. Most of these would have triggered an assert or other error before.
- ``return`` can now be used outside functions. In scripts, it does the same thing as ``exit``. In interactive mode,it sets ``$status`` without exiting (:issue:`8148`).
- An oversight prevented all syntax checks from running on commands given to ``fish -c`` (:issue:`8171`). This includes checks such as ``exec`` not being allowed in a pipeline, and ``$$`` not being a valid variable. Generally, another error was generated anyway.
- ``fish_indent`` now correctly reformats tokens that end with a backslash followed by a newline (:issue:`8197`).
- ``commandline`` gained an ``--is-valid`` option to check if the commandline is syntactically valid and complete. This allows basic implementation of transient prompts (:issue:`8142`).
- ``commandline`` gained an ``--is-valid`` option to check if the command line is syntactically valid and complete. This allows basic implementation of transient prompts (:issue:`8142`).
- ``commandline`` gained a ``--paging-full-mode`` option to check if the pager is showing all the possible lines (no "7 more rows" message) (:issue:`8485`).
- List expansion correctly reports an error when used with all zero indexes (:issue:`8213`).
- Running ``fish`` with a directory instead of a script as argument (e.g. ``fish .``) no longer leads to an infinite loop. Instead it errors out immediately (:issue:`8258`)
- Running ``fish`` with a directory instead of a script as argument (eg ``fish .``) no longer leads to an infinite loop. Instead it errors out immediately (:issue:`8258`)
- Some error messages occuring after fork, like "text file busy" have been replaced by bespoke error messages for fish (like "File is currently open for writing"). This also restores error messages with current glibc versions that removed sys_errlist (:issue:`8234`, :issue:`4183`).
- The ``realpath`` builtin now also squashes leading slashes with the ``--no-symlinks`` option (:issue:`8281`).
- When trying to ``cd`` to a dangling (broken) symbolic link, fish will print an error noting that the target is a broken link (:issue:`8264`).
- On MacOS terminals that are not granted permissions to access a folder, ``cd`` would print a spurious "rotten symlink" error, which has been corrected to "permission denied" (:issue:`8264`).
- Since fish 3.0, for-loops would trigger a variable handler an additional time before the loop was entered. This has been corrected (:issue:`8384`).
- Since fish 3.0, ``for`` loops would trigger a variable handler function before the loop was entered. As the variable had not actually changed or been set, this was a spurious event and has been removed (:issue:`8384`).
- ``math`` now correctly prints negative values and values larger than ``2**31`` when in hex or octal bases (:issue:`8417`).
- ``dirs`` always produces an exit status of 0, instead of sometimes returning 1 (:issue:`8211`).
- ``cd ""`` no longer crashes fish (:issue:`8147`).
- ``set --query`` can now query whether a variable is a pathvar via ``--path`` or ``--unpath`` (:issue:`8494`).
- ``set --query`` can now query whether a variable is a path variable via ``--path`` or ``--unpath`` (:issue:`8494`).
- Tilde characters (``~``) produced by custom completions are no longer escaped when applied to the command line, making it easier to use the output of a recursive ``complete -C`` in completion scripts (:issue:`4570`).
- Most ``string`` subcommands no longer print a final newline if such is missing from stdin (:issue:`3847`).
- ``set --show`` reports when a variable is read-only (:issue:`8179`).
- Erasing ``$fish_emoji_width`` will reset fish to the default guessed emoji width (:issue:`8274`).
- The ``la`` function no longer lists entries for "." and "..", matching other systems defaults (:issue:`8519`).
- ``abbr -q`` returns the correct exit status when given multiple abbreviation names as arguments (:issue:`8431`).
- ``command -v`` returns an exit status of 127 instead of 1 if no command was found (:issue:`8547`).
- ``argparse`` with ``--ignore-unknown`` no longer breaks with multiple unknown options in a short option group (:issue:`8637`).
- Comments inside command substitutions or brackets now correctly ignore parentheses, quotes, and brackets (:issue:`7866`, :issue:`8022`, :issue:`8695`).
- ``complete -C`` supports a new ``--escape`` option, which turns on escaping in returned completion strings (:issue:`3469`).
- Invalid byte or unicode escapes like ``\Utest`` or ``\xNotHex`` are now a tokenizer error instead of causing the token to be truncated (:issue:`8545`).
Interactive improvements
------------------------
- Vi mode cursors are now set properly after :kbd:`Control-C`. (:issue:`8125`).
- Vi mode cursors are enabled in Apple Terminal (:issue:`8167`).
- Vi mode cursors are now set properly after :kbd:`Control-C` (:issue:`8125`).
- ``funced`` will try to edit the whole file containing a function definition, if there is one (:issue:`391`).
- Running a commandline consisting of just spaces now deletes an ephemeral (starting with space) history item again (:issue:`8232`).
- Running a command line consisting of just spaces now deletes an ephemeral (starting with space) history item again (:issue:`8232`).
- Command substitutions no longer respect job control, instead running inside fish's own process group (:issue:`8172`). This more closely matches other shells, and improves :kbd:`Control-C` reliability inside a command substitution.
- ``history`` and ``__fish_print_help`` now properly support ``less`` before version 530, including the version that ships with macOS. (:issue:`8157`).
- ``help`` now knows which section is in which document again (:issue:`8245`).
- fish's highlighter will now color options (starting with ``-`` or ``--``) with the color given in the new $fish_color_option, up to the first ``--``. It falls back on $fish_color_param, so nothing changes for existing setups (:issue:`8292`).
- When executing a command, abbreviations are no longer expanded when the cursor is separated from the command by spaces, making it easier to suppress abbreviation expansion of commands without arguments. (:issue:`8423`).
- ``fish_key_reader``'s output was simplified. By default it now only prints a bind statement, the full per-character timing information can be gotten with a new ``--verbose`` switch. (:issue:`8467`)
- Custom completions are now also loaded for commands that contain tildes or variables like ``~/$bin/fish`` (:issue:`8442`).
- ``fish_key_reader``'s output was simplified. By default, it now only prints a bind statement. The previous per-character timing information can be seen with a new ``--verbose`` switch (:issue:`8467`).
- Custom completions are now also loaded for commands that contain tildes or variables like ``~/bin/fish`` or ``$PWD/fish`` (:issue:`8442`).
- Command lines spanning multiple lines will not be overwritten by the completion pager when it fills the entire terminal (:issue:`8509`, :issue:`8405`).
- When redrawing a multiline prompt, the old prompt is now properly cleared (:issue:`8163`).
- Interactive completion would occasionally ignore the last word on the command line due to a race condition. This has been fixed (:issue:`8175`).
- Propagation of universal variables from a fish process that is closing is faster (:issue:`8209`).
- The command line is drawn in the correct place if the prompt ends with a newline (:issue:`8298`).
- ``history`` learned a new subcommand ``clear-session`` to erase all history from the current session (:issue:`5791`).
- Pressing :kbd:`Control-C` in ``fish_key_reader`` will no longer print the incorrect "Press [ctrl-C] again to exit" message (:issue:`8510`).
- The default command-not-found handler for Fedora/PackageKit now passes the whole command line, allowing for functionality such as running the suggested command directly (:issue:`8579`).
- When looking for locale information, the Debian configuration is now used when available (:issue:`8557`).
- Pasting text containing quotes from the clipboard trims spaces more appropriately (:issue:`8550`).
- The clipboard bindings ignore X-based clipboard programs if the ``DISPLAY`` environment variable is not set, which helps prefer the Windows clipboard when it is available (such as on WSL).
- ``funcsave`` will remove a saved copy of a function that has been erased with ``functions --erase``.
- The Web-based configuration tool gained a number of improvements, including the ability to set pager colors.
- The default ``fish_title`` prints a shorter title with shortened $PWD and no more redundant "fish" (:issue:`8641`).
- Holding down an arrow key won't freeze the terminal with long periods of flashing (:issue:`8610`).
- Multi-char bindings are no longer interrupted if a signal handler enqueues an event. (:issue:`8628`).
New or improved bindings
^^^^^^^^^^^^^^^^^^^^^^^^
- :kbd:`Escape` can now bound without breaking arrow key bindings (:issue:`8428`).
- The :kbd:`Alt-H` binding (to open a command’s manual page) now also ignores ``command`` (:issue:`8447`).
Improved prompts
^^^^^^^^^^^^^^^^
- The ``fish_status_to_signal`` helper function returns the correct signal names for the current platform, rather than Linux (:issue:`8530`).
- The ``prompt_pwd`` helper function learned a ``--full-length-dirs N`` option to keep the last N directory components unshortened. In addition the number of characters to shorten each component should be shortened to can now be given as ``-d N`` or ``--dir-length N``. (:issue:`8208`)::
> prompt_pwd --full-length-dirs 2 -d 1 ~/dev/fish-shell/share/tools/web_config
@ -107,32 +140,47 @@ Completions
^^^^^^^^^^^
- Added completions for:
- ``istioctl`` (:issue:`8343`)
- ``black`` (:issue:`8123`)
- ``exif`` (:issue:`8246`)
- ``gping`` (:issue:`8181`)
- Angular's ``ng`` (:issue:`8111`)
- ``zef`` (:issue:`8114`)
- ``rakudo`` (:issue:`8113`)
- Apple's ``shortcuts``
- ``argparse`` (:issue:`8434`)
- ``asd`` (:issue:`8759`)
- ``az`` (:issue:`8141`)
- ``qmk`` (:issue:`8180`)
- ``cpupower``
- ``dart``
- ``sbcl``
- ``roswell``
- ``clasp``
- Windows Subsystem for Linux (WSL)'s ``wslpath`` (:issue:`8364`)
- Various wine tools (:issue:`8411`)
- mono (:issue:`8415`)
- elvish (:issue:`8416`)
- pabcnet_clear (:issue:`8421`)
- ``ethtool``
- ``black`` (:issue:`8123`)
- ``clasp`` (:issue:`8373`)
- ``cpupower`` (:issue:`8302`)
- ``dart`` (:issue:`8315`)
- ``dscacheutil``
- ``elvish`` (:issue:`8416`)
- ``ethtool`` (:issue:`8283`)
- ``exif`` (:issue:`8246`)
- ``findstr`` (:issue:`8481`)
- ``git-sizer`` (:issue:`8156`)
- ``gnome-extensions`` (:issue:`8732`)
- ``gping`` (:issue:`8181`)
- ``isatty`` (:issue:`8609`)
- ``istioctl`` (:issue:`8343`)
- ``kmutil``
- ``shortcuts``
- ``kubectl`` (:issue:`8734`)
- ``matlab`` (:issue:`8505`)
- ``mono`` (:issue:`8415`) and related tools ``csharp``, ``gacutil``, ``gendarme``, ``ikdasm``, ``ilasm``, ``mkbundle``, ``monodis``, ``monop``, ``sqlsharp`` and ``xsp`` (:issue:`8452`)
- Angular's ``ng`` (:issue:`8111`)
- ``nodeenv`` (:issue:`8533`)
- ``octave`` (:issue:`8505`)
- ``pabcnet_clear`` (:issue:`8421`)
- ``qmk`` (:issue:`8180`)
- ``rakudo`` (:issue:`8113`)
- ``rc-status`` (:issue:`8757`)
- ``roswell`` (:issue:`8330`)
- ``sbcl`` (:issue:`8330`)
- ``starship`` (:issue:`8520`)
- ``topgrade`` (:issue:`8651`)
- ``wine``, ``wineboot`` and ``winemaker`` (:issue:`8411`)
- Windows Subsystem for Linux (WSL)'s ``wslpath`` (:issue:`8364`)
- Windows' ``color`` (:issue:`8483`), ``attrib``, ``attributes``, ``choice``, ``clean``, ``cleanmgr``, ``cmd``, ``cmdkey``, ``comp``, ``forfiles``, ``powershell``, ``reg``, ``schtasks``, ``setx`` (:issue:`8486`)
- ``zef`` (:issue:`8114`)
- Improvements to many completions, especially for ``git`` aliases (:issue:`8129`) and subcommands (:issue:`8134`).
- Add missing completions for the ``-p`` option of ``xbps-query``.
- The ``fish_is_nth_token`` function, which is particularly useful in completions for identifying the token number within the command line, replaces various internal functions to do the same (:issue:`8008`).
- Improvements to many completions, especially for ``git`` aliases (:issue:`8129`), subcommands (:issue:`8134`) and submodules (:issue:`8716`).
- Many adjustments to complete correct options for system utilities on BSD and macOS.
- When evaluating custom completions, the command line state no longer includes variable overrides (``var=val``). This unbreaks completions that read ``commandline -op``.
Improved terminal support
^^^^^^^^^^^^^^^^^^^^^^^^^
@ -141,17 +189,26 @@ Improved terminal support
- fish now assumes Unicode 9+ widths for emoji under iTerm 2 (:issue:`8200`).
- Skin-tone emoji modifiers (U+1F3FB through U+1F3FF) are now measured as width 0 (:issue:`8275`).
- fish's escape sequence removal now also knows Tmux's wrapped escapes.
- Vi mode cursors are enabled in Apple Terminal.app (:issue:`8167`).
- Vi cursor shaping and $PWD reporting is now also enabled on foot (:issue:`8422`).
- ``ls`` will use colors also on newer versions of Apple Terminal.app (:issue:`8309`).
- The :kbd:`Delete` and :kbd:`Shift-Tab` keys work more reliably under ``st`` (:issue:`8352`, :issue:`8354`).
Other improvements
------------------------------
- Fish's test suite now uses ``ctest``, and has become much faster to run. It is now also possible to run only specific tests. (:issue:`7851`)
- The HTML version of the documentation now includes copy buttons for any code examples if JavaScript is available (:issue:`8218`).
------------------
- Fish's test suite now uses ``ctest``, and has become much faster to run. It is now also possible to run only specific tests with targets named ``test_$filename`` - ``make test_set.fish`` only runs the set.fish test. (:issue:`7851`)
- The HTML version of the documentation now includes copy buttons for code examples (:issue:`8218`).
- The HTML version of the documentation and the web-based configuration tool now pick more modern system fonts instead of falling back to Arial and something like Courier New most of the time (:issue:`8632`).
- The Debian & Ubuntu package linked from fishshell.com is now a single package, rather than split into ``fish`` and ``fish-common`` (:issue:`7845`).
- The macOS installer does not assert that Rosetta is required to install fish on machines with Apple Silicon (:issue:`8566`).
- The macOS installer now cleans up previous .pkg installations when upgrading. (:issue:`2963`).
For distributors
----------------
- The minimum version of CMake required to build fish was raised to 3.5.0.
- The minimum version of CMake required to build fish is now 3.5.0.
- The CMake installation supports absolute paths for ``CMAKE_INSTALL_DATADIR`` (:issue:`8150`).
- Building using NetBSD curses works on any platform (:issue:`8087`).
- The build system now uses the default linker instead of forcing use of the gold or lld linker (:issue:`8152`).
--------------
@ -184,7 +241,7 @@ Deprecations and removed features
---------------------------------
- The ``$fish_history`` value "default" is no longer special. It used to be treated the same as "fish" (:issue:`7650`).
- Redirection to standard error with the ``^`` character has been disabled by default. It can be turned back on using the ``stderr-nocaret`` feature flag, but will eventually be disabled completely (:issue:`7105`).
- Specifying an initial tab to ``fish_config`` now only works with ``fish_config browse`` (e.g. ``fish_config browse variables``), otherwise it would interfere with the new ``prompt`` subcommand (see below) (:issue:`7958`).
- Specifying an initial tab to ``fish_config`` now only works with ``fish_config browse`` (eg ``fish_config browse variables``), otherwise it would interfere with the new ``prompt`` subcommand (see below) (:issue:`7958`).
Scripting improvements
----------------------
@ -3293,3 +3350,5 @@ to call ttyname() on OS X.
We’ve got some work to do to be as lean as bash, but we’re on the right
track.
.. vim: ft=rst : tw=0 :

2
CMakeLists.txt
View File

@ -110,7 +110,7 @@ set(FISH_SRCS
src/null_terminated_array.cpp src/operation_context.cpp src/output.cpp
src/pager.cpp src/parse_execution.cpp src/parse_tree.cpp src/parse_util.cpp
src/parser.cpp src/parser_keywords.cpp src/path.cpp src/postfork.cpp
src/proc.cpp src/reader.cpp src/redirection.cpp src/sanity.cpp src/screen.cpp
src/proc.cpp src/reader.cpp src/redirection.cpp src/screen.cpp
src/signal.cpp src/termsize.cpp src/timer.cpp src/tinyexpr.cpp
src/tokenizer.cpp src/topic_monitor.cpp src/trace.cpp src/utf8.cpp src/util.cpp
src/wait_handle.cpp src/wcstringutil.cpp src/wgetopt.cpp src/wildcard.cpp

2
COPYING
View File

@ -1,7 +1,7 @@
Fish is a smart and user-friendly command line shell.
Copyright (C) 2005-2009 Axel Liljencrantz
Copyright (C) 2009-2021 fish-shell contributors
Copyright (C) 2009-2022 fish-shell contributors
fish is free software.

17
README.rst
View File

@ -48,8 +48,8 @@ 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
sudo apt update
sudo apt install fish
Instructions for other distributions may be found at
`fishshell.com <https://fishshell.com>`__.
@ -212,7 +212,7 @@ On Debian or Ubuntu you want:
::
sudo apt-get install build-essential cmake ncurses-dev libncurses5-dev libpcre2-dev gettext
sudo apt install build-essential cmake ncurses-dev libncurses5-dev libpcre2-dev gettext
On RedHat, CentOS, or Amazon EC2:
@ -231,15 +231,12 @@ 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).
channel <https://gitter.im/fish-shell/fish-shell>`__. Or use the `fish tag
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.
Found a bug? Have an awesome idea? Please `open an
issue <https://github.com/fish-shell/fish-shell/issues/new>`__.
.. |Build Status| image:: https://github.com/fish-shell/fish-shell/workflows/C/C++%20CI/badge.svg
.. |Build Status| image:: https://github.com/fish-shell/fish-shell/workflows/make%20test/badge.svg
:target: https://github.com/fish-shell/fish-shell/actions

20
benchmarks/driver.sh
View File

@ -9,20 +9,32 @@ FISH_PATH=$1
FISH2_PATH=$2
BENCHMARKS_DIR=$(dirname "$0")/benchmarks
quote() {
# Single-quote the given string for a POSIX shell, except in common cases that don't need it.
printf %s "$1" |
sed "/[^[:alnum:]\/.-]/ {
s/'/'\\\''/g
s/^/'/
s/\$/'/
}"
}
for benchmark in "$BENCHMARKS_DIR"/*; do
basename "$benchmark"
[ -n "$FISH2_PATH" ] && echo "$FISH_PATH"
${FISH_PATH} --print-rusage-self "$benchmark" > /dev/null
"${FISH_PATH}" --print-rusage-self "$benchmark" > /dev/null
if [ -n "$FISH2_PATH" ]; then
echo "$FISH2_PATH"
${FISH2_PATH} --print-rusage-self "$benchmark" > /dev/null
"${FISH2_PATH}" --print-rusage-self "$benchmark" > /dev/null
fi
if command -v hyperfine >/dev/null 2>&1; then
cmd1="$(quote "${FISH_PATH}") $(quote "$benchmark") > /dev/null"
if [ -n "$FISH2_PATH" ]; then
hyperfine "${FISH_PATH} $benchmark > /dev/null" "${FISH2_PATH} $benchmark > /dev/null"
cmd2="$(quote "${FISH2_PATH}") $(quote "$benchmark") > /dev/null"
hyperfine "$cmd1" "$cmd2"
else
hyperfine "${FISH_PATH} $benchmark > /dev/null"
hyperfine "$cmd1"
fi
fi
done

1
build_tools/bin/README.txt
View File

@ -1 +0,0 @@
mac_xar_116 is http://mackyle.github.io/xar/, compiled for Mac. It is used by mac_sign_package.sh as a replacement for productsign.

BIN
build_tools/bin/mac_xar_116
View File

Binary file not shown.

122
build_tools/mac_sign_package.sh
View File

@ -1,122 +0,0 @@
#!/usr/bin/env bash
# This codesigns a Mac .pkg (installer) file.
# Normally we could use `productsign` but that no longer produces
# installers compatible with 10.11.
# See https://github.com/fish-shell/fish-shell/issues/7656
#
# So instead we use the flow described here:
# http://users.wfu.edu/cottrell/productsign/productsign_linux.html
#
# This script expects the following:
#
# 1. A variable $MAC_PRODUCTSIGN_CERTS_DIR pointing at a directory containing files cert00, cert01, cert02
# 2. A variable $MAC_PRODUCTSIGN_P12_FILE containing the "Mac Developer ID Installer" keychain item, exported as p12. See below.
die() { echo "$*" 1>&2 ; exit 1; }
# Exit on error.
set -e
# Our input package file.
INPUT_PKG=$(realpath $1)
test -f "$INPUT_PKG" || die "${INPUT_PKG} not a valid package"
# Find where our mac_xar_116 binary is.
XAR_116="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"/bin/mac_xar_116
# Here's what we need to be set.
test -f "${MAC_PRODUCTSIGN_P12_FILE}" || die "MAC_PRODUCTSIGN_P12_FILE not set or not a p12 file"
test -d "${MAC_PRODUCTSIGN_CERTS_DIR}" || die "MAC_PRODUCTSIGN_CERTS_DIR not set or not a directory"
test -f "${MAC_PRODUCTSIGN_CERTS_DIR}/cert00" \
&& test -f "${MAC_PRODUCTSIGN_CERTS_DIR}/cert01" \
&& test -f "${MAC_PRODUCTSIGN_CERTS_DIR}/cert02" \
|| die "MAC_PRODUCTSIGN_CERTS_DIR does not contain cert00, cert01, cert02"
test -x "${XAR_116}" || die "mac_xar_116 binary not found or executable at ${XAR_116}"
TMP=$(mktemp -d)
KEYFILE="${TMP}/key.pem"
DIGFILE="${TMP}/digestinfo.dat"
SIGFILE="${TMP}/signature.dat"
set -x
openssl pkcs12 -in "${MAC_PRODUCTSIGN_P12_FILE}" -nodes | openssl rsa -out "${KEYFILE}"
test -f "${KEYFILE}" || die "openssl did not create key.pem"
SIGSIZE=$(openssl dgst -sign "${KEYFILE}" -binary < /dev/null | wc -c | xargs)
# Prepare data for signing.
${XAR_116} --sign -f ${INPUT_PKG} --digestinfo-to-sign "${DIGFILE}" \
--sig-size "${SIGSIZE}" \
--cert-loc "${MAC_PRODUCTSIGN_CERTS_DIR}/cert00" \
--cert-loc "${MAC_PRODUCTSIGN_CERTS_DIR}/cert01" \
--cert-loc "${MAC_PRODUCTSIGN_CERTS_DIR}/cert02"
# Create the signature.
openssl rsautl -sign -inkey "${KEYFILE}" -in "${DIGFILE}" -out "${SIGFILE}"
# Add it to the archive, in place, then move it back.
${XAR_116} --inject-sig "${SIGFILE}" -f "${INPUT_PKG}"
# Remove all our junk.
rm -rf "${TMP}"
# Check the signature!
pkgutil --check-signature "${INPUT_PKG}"
# The following is taken from http://users.wfu.edu/cottrell/productsign/productsign_linux.html
# Saved here for posterity.
# Signing a Mac OS X package on Linux
# Premises
# You are a software developer who's at home on Linux but you want to produce builds of your software for other platforms, including Mac OS X.
# You've already figured out cross-compilation. And in regard to OS X you've figured out how to build a (flat) pkg file on Linux – or if not, you can do so quite quickly by looking at the bomutils doc: https://github.com/hogliux/bomutils.
# You are grudgingly willing to pay the Apple tax (the fee for becoming a registered developer) so that you can get a certificate with which to sign your package, in order that your gentle users don't get off-putting messages from Gatekeeper.
# But you're wondering how to sign your package without having to use Apple's productsign on a Mac.
# If you match on all points, we're in business! Here's the drill as I have figured it out. You will need: openssl, recent xar (see below), and one-time access to an actual Mac.
# Procedure
# Step 0: Build your program and create an OS X pkg file (xar archive). This you will do (on Linux) whenever you want to create a new release or snapshot.
# Step 1: This is a one-time step to be performed on a Mac. There may be a way around it, but I'm not aware of one. Please let me know if you're cleverer than I when it comes to certificates and all that. But anyway, follow the Apple directions for installing your developer certificate(s) on OS X, and use productsign to sign your package on the Mac – just this once! (Copy it across from Linux.) And then, before leaving the Mac, open Keychain Access and find your developer cert, the one with "Developer ID Installer" in its title (it should have a private key tucked under it). Highlight it and select "Export items" under the File menu to save as a p12 file. Copy your signed package and the exported p12 file (let's say it's called certs.p12) to your Linux box.
# Step 2: Back on Linux you're going to need a reasonably recent version of xar, specifically 1.6.1 or higher to support signing. Arch Linux installs xar 1.6.1 if you do pacman -S xar. Fedora's dnf install xar gets version 1.5, which won't do the job. I don't know about other distros, but if need be you can find the source for xar 1.6.1 at http://mackyle.github.io/xar/. Anyway, here's another one-time step: you'll extract the certs you need from the pkg file that you signed on the Mac, and the private key from the p12 file you exported from Keychain Access. (You'll need the passphrase that you set on the p12 when exporting it, so I hope you haven't forgotten that.)
# I'll assume (unimaginatively) that your package is called foo.pkg.
# # extract the certs from signed foo.pkg
# mkdir certs
# xar -f foo.pkg --extract-certs certs
# You should find certs00, certs01 and probably certs02 in the certs directory. Perhaps more.
# # extract the private key from certs.p12 (requires passphrase)
# openssl pkcs12 -in certs.p12 -nodes | openssl rsa -out key.pem
# At this point you have the materials to sign future versions of your package natively on Linux. I'll now assume that a new unsigned foo.pkg is sitting in a directory containing the key.pem generated above and also the certs subdirectory created above. So now (with many thanks to mackyle!) you do:
# PKG=foo.pkg
# # determine the size of the signature
# : | openssl dgst -sign key.pem -binary | wc -c > siglen.txt
# # prepare data for signing -- may have to adjust depending
# # on the contents of the certs subdir in your case
# xar --sign -f $PKG --digestinfo-to-sign digestinfo.dat \
# --sig-size `cat siglen.txt` \
# --cert-loc certs/cert00 \
# --cert-loc certs/cert01 \
# --cert-loc certs/cert02
# # create the signature
# openssl rsautl -sign -inkey key.pem -in digestinfo.dat \
# -out signature.dat
# # stuff it into the archive
# xar --inject-sig signature.dat -f $PKG
# # and clean up
# rm -f signature.dat digestinfo.dat siglen.txt
# From this point on, just build your package on Linux and sign it on Linux using xar along with the certs and key that you got from the Mac.

13
build_tools/make_pkg.sh
View File

@ -31,17 +31,10 @@ mkdir -p "$PKGDIR/build" "$PKGDIR/root" "$PKGDIR/intermediates" "$PKGDIR/dst"
pkgbuild --scripts "$SRC_DIR/build_tools/osx_package_scripts" --root "$PKGDIR/root/" --identifier 'com.ridiculousfish.fish-shell-pkg' --version "$VERSION" "$PKGDIR/intermediates/fish.pkg"
productbuild --package-path "$PKGDIR/intermediates" --distribution "$SRC_DIR/build_tools/osx_distribution.xml" --resources "$SRC_DIR/build_tools/osx_package_resources/" "$OUTPUT_PATH/fish-$VERSION.pkg"
# Here is the historical way to sign the installer package.
# But when run on macOS 11.1, the resulting installers don't work on 10.11.
# So we have our own script instead. See issue #7656.
# Also see https://developer.apple.com/forums/thread/664842
# If/when productsign is fixed to support 10.11, we can switch back to this.
# MAC_PRODUCTSIGN_ID=${MAC_PRODUCTSIGN_ID:--}
# productsign --sign "${MAC_PRODUCTSIGN_ID}" "$OUTPUT_PATH/fish-$VERSION.pkg" "$OUTPUT_PATH/fish-$VERSION-signed.pkg" && mv "$OUTPUT_PATH/fish-$VERSION-signed.pkg" "$OUTPUT_PATH/fish-$VERSION.pkg"
"$SRC_DIR/build_tools/mac_sign_package.sh" "$OUTPUT_PATH/fish-$VERSION.pkg"
MAC_PRODUCTSIGN_ID=${MAC_PRODUCTSIGN_ID:--}
productsign --sign "${MAC_PRODUCTSIGN_ID}" "$OUTPUT_PATH/fish-$VERSION.pkg" "$OUTPUT_PATH/fish-$VERSION-signed.pkg" && mv "$OUTPUT_PATH/fish-$VERSION-signed.pkg" "$OUTPUT_PATH/fish-$VERSION.pkg"
# Make the app
{ cd "$PKGDIR/build" && make signed_fish_macapp && zip -r "$OUTPUT_PATH/fish-$VERSION.app.zip" fish.app; }
{ cd "$PKGDIR/build" && make -j 12 signed_fish_macapp && zip -r "$OUTPUT_PATH/fish-$VERSION.app.zip" fish.app; }
rm -r "$PKGDIR"

5
build_tools/osx_distribution.xml
View File

@ -1,10 +1,11 @@
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<installer-gui-script minSpecVersion="1">
<title>fish shell</title>
<welcome file="welcome.rtf"/>
<welcome file="welcome.html" mime-type="text/html"/>
<background file="terminal_logo.png" scaling="proportional" alignment="bottomleft"/>
<pkg-ref id="com.ridiculousfish.fish-shell-pkg"/>
<options customize="never" require-scripts="false"/>
<options hostArchitectures="arm64,x86_64" rootVolumeOnly="true"/>
<options customize="never" require-scripts="true"/>
<choices-outline>
<line choice="default">
<line choice="com.ridiculousfish.fish-shell-pkg"/>

29
build_tools/osx_package_resources/welcome.html Normal file
View File

@ -0,0 +1,29 @@
<html>
<head>
<style>
body {
font-family: system-ui, -apple-system, "Helvetica Neue", sans-serif;
font-size: 10pt;
}
code, tt {
font-family: ui-monospace, Menlo, monospace;
}
</style>
</head>
<body>
<p>
<strong>fish</strong> is a smart and user-friendly command line shell. For more information, visit <a href="https://fishshell.com">fishshell.com</a>.
</p>
<p>
<strong>fish</strong> will be installed into <tt>/usr/local/</tt>, and its path will be added to <wbr><tt>/etc/shells</tt> if necessary.
</p>
<p>
Your default shell will <em>not</em> be changed. To make <strong>fish</strong> your login shell after the installation, run:
</p>
<p>
<code>chsh -s /usr/local/bin/fish</code>
</p>
<p>Enjoy! Bugs can be reported on <a href="https://github.org/fish-shell/fish-shell/">GitHub</a>.</p>
</body>
</html>

26
build_tools/osx_package_resources/welcome.rtf
View File

@ -1,26 +0,0 @@
{\rtf1\ansi\ansicpg1252\cocoartf1485\cocoasubrtf410
{\fonttbl\f0\fnil\fcharset0 HelveticaNeue;\f1\fnil\fcharset0 Menlo-Regular;}
{\colortbl;\red255\green255\blue255;}
{\*\expandedcolortbl;\csgenericrgb\c100000\c100000\c100000;}
{\info
{\author dlkfjslfjsfdlkfk}}\margl1440\margr1440\vieww10800\viewh8400\viewkind0
\pard\tx720\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\pardirnatural\partightenfactor0
\f0\fs30 \cf0 Fish is a smart and user friendly command line shell. For more information, visit {\field{\*\fldinst{HYPERLINK "https://fishshell.com"}}{\fldrslt https://fishshell.com}}\
\
fish will be installed into
\f1\fs26 /usr/local/
\f0\fs30 , and fish will be added to
\f1\fs26 /etc/shells
\f0\fs30 if necessary.\
\
Your default shell will
\i not
\i0 be changed. To make fish your default, run:\
\
\f1 chsh -s /usr/local/bin/fish
\f0 \
\
Enjoy!\
}

2
build_tools/osx_package_scripts/postinstall
View File

@ -1,3 +1,3 @@
#!/bin/sh -x
./add-shell /usr/local/bin/fish > /tmp/fish_postinstall_output.log
./add-shell ${DSTVOLUME}usr/local/bin/fish

7
build_tools/osx_package_scripts/preinstall Executable file
View File

@ -0,0 +1,7 @@
#!/bin/sh -x
echo "Removing any previous installation"
pkgutil --pkg-info ${INSTALL_PKG_SESSION_ID} && pkgutil --only-files --files ${INSTALL_PKG_SESSION_ID} | while read installed
do rm -v ${DSTVOLUME}${installed}
done
echo "... removed"

7
cmake/ConfigureChecks.cmake
View File

@ -115,7 +115,14 @@ check_struct_has_member("struct stat" st_mtim.tv_nsec "sys/stat.h" HAVE_STRUCT_S
LANGUAGE CXX)
check_include_file_cxx(sys/ioctl.h HAVE_SYS_IOCTL_H)
check_include_file_cxx(sys/select.h HAVE_SYS_SELECT_H)
# glibc 2.30 deprecated <sys/sysctl.h> because that's what glibc does.
# Checking for that here rather than hardcoding a check on the glibc
# version in the C++ sources at point of use makes more sense.
SET(OLD_CMAKE_C_FLAGS "${CMAKE_C_FLAGS}")
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Werror")
check_include_files("sys/types.h;sys/sysctl.h" HAVE_SYS_SYSCTL_H)
SET(CMAKE_C_FLAGS "${OLD_CMAKE_C_FLAGS}")
check_cxx_symbol_exists(eventfd sys/eventfd.h HAVE_EVENTFD)
check_cxx_symbol_exists(pipe2 unistd.h HAVE_PIPE2)

5
cmake/Docs.cmake
View File

@ -9,7 +9,6 @@ include(FeatureSummary)
set(SPHINX_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/doc_src")
set(SPHINX_ROOT_DIR "${CMAKE_CURRENT_BINARY_DIR}/user_doc")
set(SPHINX_BUILD_DIR "${SPHINX_ROOT_DIR}/build")
set(SPHINX_CACHE_DIR "${SPHINX_ROOT_DIR}/doctrees")
set(SPHINX_HTML_DIR "${SPHINX_ROOT_DIR}/html")
set(SPHINX_MANPAGE_DIR "${SPHINX_ROOT_DIR}/man")
@ -22,7 +21,7 @@ add_custom_target(sphinx-docs
-j auto
-q -b html
-c "${SPHINX_SRC_DIR}"
-d "${SPHINX_CACHE_DIR}"
-d "${SPHINX_ROOT_DIR}/.doctrees-html"
"${SPHINX_SRC_DIR}"
"${SPHINX_HTML_DIR}"
DEPENDS ${SPHINX_SRC_DIR}/fish_indent_lexer.py fish_indent
@ -35,7 +34,7 @@ add_custom_target(sphinx-manpages
-j auto
-q -b man
-c "${SPHINX_SRC_DIR}"
-d "${SPHINX_CACHE_DIR}"
-d "${SPHINX_ROOT_DIR}/.doctrees-man"
"${SPHINX_SRC_DIR}"
# TODO: This only works if we only have section 1 manpages.
"${SPHINX_MANPAGE_DIR}/man1"

6
cmake/Mac.cmake
View File

@ -1,6 +1,4 @@
set(CMAKE_OSX_DEPLOYMENT_TARGET "10.10" CACHE STRING "Minimum OS X deployment version")
# list of possibly relevent new stuff in 10.10 compared to 10.9:
# https://gist.github.com/floam/586f9c8a338357e16a97fa596b330e37
# Code signing ID on Mac.
# If this is falsey, codesigning is disabled.
@ -13,10 +11,10 @@ set(MAC_INJECT_GET_TASK_ALLOW ON CACHE BOOL "Inject get-task-allow on Mac")
# When building a Mac build, it is common for fish to link against a
# pcre2 built for the host platform (e.g. macOS 10.15) while fish wants
# to link for macOS 10.10. This warning would be of interest for releases,
# to link for macOS 10.9. This warning would be of interest for releases,
# but is just noise for daily development. Unfortunately it has no flag
# of its own, so suppress all linker warnings in debug builds.
#set(CMAKE_EXE_LINKER_FLAGS_DEBUG "${CMAKE_EXE_LINKER_FLAGS_DEBUG} -w")
set(CMAKE_EXE_LINKER_FLAGS_DEBUG "${CMAKE_EXE_LINKER_FLAGS_DEBUG} -w")
function(CODESIGN_ON_MAC target)
if((APPLE) AND (MAC_CODESIGN_ID))

10
doc_src/cmds/_.rst
View File

@ -6,9 +6,9 @@ _ - call fish's translations
Synopsis
--------
::
.. synopsis::
_ STRING...
_ STRING
Description
-----------
@ -19,19 +19,17 @@ It is equivalent to ``gettext fish STRING``, meaning it can only be used to look
It requires fish to be built with gettext support. If that support is disabled, or there is no translation it will simply echo the argument back.
The language depends on the current locale, set with ``$LANG`` and ``$LC_MESSAGES``.
The language depends on the current locale, set with :envvar:`LANG` and :envvar:`LC_MESSAGES`.
Options
-------
``_`` has no options.
``_`` takes no options.
Examples
--------
::
> _ File

75
doc_src/cmds/abbr.rst
View File

@ -6,66 +6,75 @@ abbr - manage fish abbreviations
Synopsis
--------
::
.. synopsis::
abbr --add [SCOPE] WORD EXPANSION
abbr --erase WORD...
abbr --erase WORD ...
abbr --rename [SCOPE] OLD_WORD NEW_WORD
abbr --show
abbr --list
abbr --query WORD...
abbr --query WORD ...
Description
-----------
``abbr`` manages abbreviations - user-defined words that are replaced with longer phrases after they are entered.
For example, a frequently-run command like ``git checkout`` can be abbreviated to ``gco``. After entering ``gco`` and pressing :kbd:`Space` or :kbd:`Enter`, the full text ``git checkout`` will appear in the command line.
For example, a frequently-run command like ``git checkout`` can be abbreviated to ``gco``.
After entering ``gco`` and pressing :kbd:`Space` or :kbd:`Enter`, the full text ``git checkout`` will appear in the command line.
Options
-------
The following options are available:
- ``-a WORD EXPANSION`` or ``--add WORD EXPANSION`` Adds a new abbreviation, causing WORD to be expanded to EXPANSION.
**-a** *WORD* *EXPANSION* or **--add** *WORD* *EXPANSION*
Adds a new abbreviation, causing *WORD* to be expanded to *EXPANSION*
- ``-r OLD_WORD NEW_WORD`` or ``--rename OLD_WORD NEW_WORD`` Renames an abbreviation, from OLD_WORD to NEW_WORD.
**-r** *OLD_WORD* *NEW_WORD* or **--rename** *OLD_WORD* *NEW_WORD*
Renames an abbreviation, from *OLD_WORD* to *NEW_WORD*
- ``-s`` or ``--show`` Show all abbreviations in a manner suitable for export and import.
**-s** or **--show**
Show all abbreviations in a manner suitable for import and export
- ``-l`` or ``--list`` Lists all abbreviated words.
**-l** or **--list**
Lists all abbreviated words
- ``-e WORD`` or ``--erase WORD...`` Erase the given abbreviations.
**-e** *WORD* or **--erase** *WORD* ...
Erase the given abbreviations
- ``-q`` or ``--query`` Return 0 (true) if one of the WORDs is an abbreviation.
**-q** or **--query**
Return 0 (true) if one of the *WORD* is an abbreviation.
In addition, when adding or renaming abbreviations:
**-h** or **--help**
Displays help about using this command.
- ``-g`` or ``--global`` to use a global variable.
- ``-U`` or ``--universal`` to use a universal variable (default).
In addition, when adding or renaming abbreviations, one of the following **SCOPE** options can be used:
**-g** or **--global**
Use a global variable
**-U** or **--universal**
Use a universal variable (default)
See the "Internals" section for more on them.
Examples
--------
::
abbr -a -g gco git checkout
Add a new abbreviation where ``gco`` will be replaced with ``git checkout`` global to the current shell. This abbreviation will not be automatically visible to other shells unless the same command is run in those shells (such as when executing the commands in config.fish).
Add a new abbreviation where ``gco`` will be replaced with ``git checkout`` global to the current shell.
This abbreviation will not be automatically visible to other shells unless the same command is run in those shells (such as when executing the commands in config.fish).
::
abbr -a -U l less
Add a new abbreviation where ``l`` will be replaced with ``less`` universal to all shells. Note that you omit the ``-U`` since it is the default.
Add a new abbreviation where ``l`` will be replaced with ``less`` universal to all shells.
Note that you omit the **-U** since it is the default.
::
@ -73,16 +82,12 @@ Add a new abbreviation where ``l`` will be replaced with ``less`` universal to a
Renames an existing abbreviation from ``gco`` to ``gch``.
::
abbr -e gco
Erase the ``gco`` abbreviation.
::
ssh another_host abbr -s | source
@ -91,20 +96,8 @@ Import the abbreviations defined on another_host over SSH.
Internals
---------
Each abbreviation is stored in its own global or universal variable. The name consists of the prefix ``_fish_abbr_`` followed by the WORD after being transformed by ``string escape style=var``. The WORD cannot contain a space but all other characters are legal.
Each abbreviation is stored in its own global or universal variable.
The name consists of the prefix ``_fish_abbr_`` followed by the WORD after being transformed by ``string escape style=var``.
The WORD cannot contain a space but all other characters are legal.
Defining an abbreviation with global scope is slightly faster than universal scope (which is the default). But in general you'll only want to use the global scope when defining abbreviations in a startup script like ``~/.config/fish/config.fish`` like this:
::
if status --is-interactive
abbr --add --global first 'echo my first abbreviation'
abbr --add --global second 'echo my second abbreviation'
abbr --add --global gco git checkout
# etcetera
end
You can create abbreviations interactively and they will be visible to other fish sessions if you use the ``-U`` or ``--universal`` flag or don't explicitly specify the scope and the abbreviation isn't already defined with global scope. If you want it to be visible only to the current shell use the ``-g`` or ``--global`` flag.
Abbreviations created with the **--universal** flag will be visible to other fish sessions, whilst **--global** will be limited to the current session.

18
doc_src/cmds/alias.rst
View File

@ -6,11 +6,11 @@ alias - create a function
Synopsis
--------
::
.. synopsis::
alias
alias [OPTIONS] NAME DEFINITION
alias [OPTIONS] NAME=DEFINITION
alias [--save] NAME DEFINITION
alias [--save] NAME=DEFINITION
Description
@ -21,23 +21,23 @@ Description
``fish`` marks functions that have been created by ``alias`` by including the command used to create them in the function description. You can list ``alias``-created functions by running ``alias`` without arguments. They must be erased using ``functions -e``.
- ``NAME`` is the name of the alias
- ``DEFINITION`` is the actual command to execute. The string ``$argv`` will be appended.
- ``DEFINITION`` is the actual command to execute. ``alias`` automatically appends ``$argv``, so that all parameters used with the alias are passed to the actual command.
You cannot create an alias to a function with the same name. Note that spaces need to be escaped in the call to ``alias`` just like at the command line, *even inside quoted parts*.
The following options are available:
- ``-h`` or ``--help`` displays help about using this command.
**-h** or **--help**
Displays help about using this command.
- ``-s`` or ``--save`` Automatically save the function created by the alias into your fish configuration directory using :ref:`funcsave <cmd-funcsave>`.
**-s** or **--save**
Saves the function created by the alias into your fish configuration directory using :ref:`funcsave <cmd-funcsave>`.
Example
-------
The following code will create ``rmi``, which runs ``rm`` with additional arguments on every invocation.
::
alias rmi="rm -i"
@ -55,6 +55,6 @@ The following code will create ``rmi``, which runs ``rm`` with additional argume
See more
--------
1. The :ref:`function <cmd-function>` builtin this builds on.
1. The :ref:`function <cmd-function>` command this builds on.
2. :ref:`Functions <syntax-function>`.
3. :ref:`Function wrappers <syntax-function-wrappers>`.

7
doc_src/cmds/and.rst
View File

@ -6,9 +6,9 @@ and - conditionally execute a command
Synopsis
--------
::
.. synopsis::
COMMAND1; and COMMAND2
PREVIOUS; and COMMAND
Description
-----------
@ -19,6 +19,8 @@ Description
``and`` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the :ref:`$status <variables-status>` variable.
The **-h** or **--help** option displays help about using this command.
Example
-------
@ -32,3 +34,4 @@ See Also
--------
- :ref:`or <cmd-or>` command
- :ref:`not <cmd-not>` command

62
doc_src/cmds/argparse.rst
View File

@ -6,54 +6,60 @@ argparse - parse options passed to a fish script or function
Synopsis
--------
::
.. synopsis::
argparse [OPTIONS] OPTION_SPEC... -- [ARG...]
argparse [OPTIONS] OPTION_SPEC ... -- [ARG ...]
Description
-----------
This command makes it easy for fish scripts and functions to handle arguments like how fish builtin commands handle their arguments. You pass arguments that define the known options, followed by a literal ``--``, then the arguments to be parsed (which might also include a literal ``--``). ``argparse`` then sets variables to indicate the passed options with their values, and sets $argv (and always $argv) to the remaining arguments. More on this in the :ref:`usage <cmd-argparse-usage>` section below.
This command makes it easy for fish scripts and functions to handle arguments. You pass arguments that define the known options, followed by a literal **--**, then the arguments to be parsed (which might also include a literal **--**). ``argparse`` then sets variables to indicate the passed options with their values, and sets ``$argv`` to the remaining arguments. See the :ref:`usage <cmd-argparse-usage>` section below.
Each option specification (``OPTION_SPEC``) is written in the :ref:`domain specific language <cmd-argparse-option-specification>` described below. All OPTION_SPECs must appear after any argparse flags and before the ``--`` that separates them from the arguments to be parsed.
Each option that is seen in the ARG list will result in variables named ``_flag_X``, where ``X`` is the short flag letter and the long flag name (if they are defined). For example a ``--help`` option could cause argparse to define one variable called ``_flag_h`` and another called ``_flag_help``.
Each option that is seen in the ARG list will result in variables named ``_flag_X``, where **X** is the short flag letter and the long flag name (if they are defined). For example a **--help** option could cause argparse to define one variable called ``_flag_h`` and another called ``_flag_help``.
The variables will be set with local scope (i.e., as if the script had done ``set -l _flag_X``). If the flag is a boolean (that is, it just is passed or not, it doesn't have a value) the values are the short and long flags seen. If the option is not a boolean the values will be zero or more values corresponding to the values collected when the ARG list is processed. If the flag was not seen the flag variable will not be set.
Options
-------
The following ``argparse`` options are available. They must appear before all OPTION_SPECs:
The following ``argparse`` options are available. They must appear before all *OPTION_SPEC*\ s:
- ``-n`` or ``--name`` is the command name for use in error messages. By default the current function name will be used, or ``argparse`` if run outside of a function.
**-n** or **--name**
The command name for use in error messages. By default the current function name will be used, or ``argparse`` if run outside of a function.
- ``-x`` or ``--exclusive`` should be followed by a comma separated list of short or long options that are mutually exclusive. You can use this more than once to define multiple sets of mutually exclusive options.
**-x** or **--exclusive** *OPTIONS*
A comma separated list of options that are mutually exclusive. You can use this more than once to define multiple sets of mutually exclusive options.
- ``-N`` or ``--min-args`` is followed by an integer that defines the minimum number of acceptable non-option arguments. The default is zero.
**-N** or **--min-args** *NUMBER*
The minimum number of acceptable non-option arguments. The default is zero.
- ``-X`` or ``--max-args`` is followed by an integer that defines the maximum number of acceptable non-option arguments. The default is infinity.
**-X** or **--max-args** *NUMBER*
The maximum number of acceptable non-option arguments. The default is infinity.
- ``-i`` or ``--ignore-unknown`` ignores unknown options, keeping them and their arguments in $argv instead.
**-i** or **--ignore-unknown**
Ignores unknown options, keeping them and their arguments in $argv instead.
- ``-s`` or ``--stop-nonopt`` causes scanning the arguments to stop as soon as the first non-option argument is seen. Among other things, this is useful to implement subcommands that have their own options.
**-s** or **--stop-nonopt**
Causes scanning the arguments to stop as soon as the first non-option argument is seen. Among other things, this is useful to implement subcommands that have their own options.
- ``-h`` or ``--help`` displays help about using this command.
**-h** or **--help**
Displays help about using this command.
.. _cmd-argparse-usage:
Usage
-----
To use this command, pass the option specifications (``OPTION_SPEC``), then a mandatory ``--``, and then the arguments you want to have parsed.
To use this command, pass the option specifications (**OPTION_SPEC**), a mandatory **--**, and then the arguments to be parsed.
A simple example::
argparse --name=my_function 'h/help' 'n/name=' -- $argv
or return
If ``$argv`` is empty then there is nothing to parse and ``argparse`` returns zero to indicate success. If ``$argv`` is not empty then it is checked for flags ``-h``, ``--help``, ``-n`` and ``--name``. If they are found they are removed from the arguments and local variables called ``_flag_OPTION`` are set so the script can determine which options were seen. If ``$argv`` doesn't have any errors, like a missing mandatory value for an option, then ``argparse`` exits with a status of zero. Otherwise it writes appropriate error messages to stderr and exits with a status of one.
The ``or return`` means that the function returns ``argparse``'s status if it failed, so if it goes on ``argparse`` succeeded.
@ -63,7 +69,6 @@ The ``--`` argument is required. You do not have to include any arguments after
set -l argv
argparse 'h/help' 'n/name' -- $argv
But this is not::
set -l argv
@ -78,17 +83,17 @@ Option Specifications
Each option specification consists of:
- An optional alphanumeric short flag letter, followed by a ``/`` if the short flag can be used by someone invoking your command or, for backwards compatibility, a ``-`` if it should not be exposed as a valid short flag (in which case it will also not be exposed as a flag variable).
- An optional alphanumeric short flag character, followed by a ``/`` if the short flag can be used by someone invoking your command or, for backwards compatibility, a ``-`` if it should not be exposed as a valid short flag (in which case it will also not be exposed as a flag variable).
- An optional long flag name. If not present then only the short flag letter can be used, and if that is not present either it's an error.
- An optional long flag name, which if not present the short flag can be used, and if that is also not present, an error is reported
- Nothing if the flag is a boolean that takes no argument or is an integer flag, or
- ``=`` if it requires a value and only the last instance of the flag is saved, or
- **=** if it requires a value and only the last instance of the flag is saved, or
- ``=?`` it takes an optional value and only the last instance of the flag is saved, or
- **=?** if it takes an optional value and only the last instance of the flag is saved, or
- ``=+`` if it requires a value and each instance of the flag is saved.
- **=+** if it requires a value and each instance of the flag is saved.
- Optionally a ``!`` followed by fish script to validate the value. Typically this will be a function to run. If the exit status is zero the value for the flag is valid. If non-zero the value is invalid. Any error messages should be written to stdout (not stderr). See the section on :ref:`Flag Value Validation <flag-value-validation>` for more information.
@ -160,7 +165,7 @@ Fish ships with a ``_validate_int`` function that accepts a ``--min`` and ``--ma
Example OPTION_SPECs
--------------------
Some OPTION_SPEC examples:
Some *OPTION_SPEC* examples:
- ``h/help`` means that both ``-h`` and ``--help`` are valid. The flag is a boolean and can be used more than once. If either flag is used then ``_flag_h`` and ``_flag_help`` will be set to the count of how many times either flag was seen.
@ -187,3 +192,18 @@ Some OPTION_SPEC examples:
After parsing the arguments the ``argv`` variable is set with local scope to any values not already consumed during flag processing. If there are no unbound values the variable is set but ``count $argv`` will be zero.
If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr.
Limitations
-----------
One limitation with **--ignore-unknown** is that, if an unknown option is given in a group with known options, the entire group will be kept in $argv. ``argparse`` will not do any permutations here.
For instance::
argparse --ignore-unknown h -- -ho
echo $_flag_h # is -h, because -h was given
echo $argv # is still -ho
This limitation may be lifted in future.
Additionally, it can only parse known options up to the first unknown option in the group - the unknown option could take options, so it isn't clear what any character after an unknown option means.

13
doc_src/cmds/begin.rst
View File

@ -6,30 +6,28 @@ begin - start a new block of code
Synopsis
--------
::
begin; [COMMANDS...;] end
.. synopsis::
begin; [COMMANDS ...]; end
Description
-----------
``begin`` is used to create a new block of code.
A block allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like ``and``.
A block allows the introduction of a new :ref:`variable scope <variables-scope>`, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like ``and``.
The block is unconditionally executed. ``begin; ...; end`` is equivalent to ``if true; ...; end``.
``begin`` does not change the current exit status itself. After the block has completed, ``$status`` will be set to the status returned by the most recent command.
The **-h** or **--help** option displays help about using this command.
Example
-------
The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends.
::
begin
@ -45,8 +43,6 @@ The following code sets a number of variables inside of a block scope. Since the
In the following code, all output is redirected to the file out.html.
::
begin
@ -57,4 +53,3 @@ In the following code, all output is redirected to the file out.html.
end
...
end > out.html

6
doc_src/cmds/bg.rst
View File

@ -6,9 +6,9 @@ bg - send jobs to background
Synopsis
--------
::
.. synopsis::
bg [PID...]
bg [PID ...]
Description
-----------
@ -24,6 +24,8 @@ When at least one of the arguments isn't a valid job specifier,
When all arguments are valid job specifiers, ``bg`` will background all matching jobs that exist.
The **-h** or **--help** option displays help about using this command.
Example
-------

278
doc_src/cmds/bind.rst
View File

@ -5,14 +5,14 @@ bind - handle fish key bindings
Synopsis
--------
::
.. synopsis::
bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [--preset | --user] [(-s | --silent)] [(-k | --key)] SEQUENCE COMMAND [COMMAND...]
bind [(-M | --mode) MODE] [(-k | --key)] [--preset] [--user] SEQUENCE
bind (-K | --key-names) [(-a | --all)] [--preset] [--user]
bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [--preset | --user] [-s | --silent] [-k | --key] SEQUENCE COMMAND ...
bind [(-M | --mode) MODE] [-k | --key] [--preset] [--user] SEQUENCE
bind (-K | --key-names) [-a | --all] [--preset] [--user]
bind (-f | --function-names)
bind (-L | --list-modes)
bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] (-a | --all | [(-k | --key)] SEQUENCE [SEQUENCE...])
bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] [-a | --all] | [-k | --key] SEQUENCE ...
Description
-----------
@ -47,179 +47,279 @@ Options
-------
The following options are available:
- ``-k`` or ``--key`` Specify a key name, such as 'left' or 'backspace' instead of a character sequence
**-k** or **--key**
Specify a key name, such as 'left' or 'backspace' instead of a character sequence
- ``-K`` or ``--key-names`` Display a list of available key names. Specifying ``-a`` or ``--all`` includes keys that don't have a known mapping
**-K** or **--key-names**
Display a list of available key names. Specifying **-a** or **--all** includes keys that don't have a known mapping
- ``-f`` or ``--function-names`` Display a list of available input functions
**-f** or **--function-names**
Display a list of available input functions
- ``-L`` or ``--list-modes`` Display a list of defined bind modes
**-L** or **--list-modes**
Display a list of defined bind modes
- ``-M MODE`` or ``--mode MODE`` Specify a bind mode that the bind is used in. Defaults to "default"
**-M MODE** or **--mode** *MODE*
Specify a bind mode that the bind is used in. Defaults to "default"
- ``-m NEW_MODE`` or ``--sets-mode NEW_MODE`` Change the current mode to ``NEW_MODE`` after this binding is executed
**-m NEW_MODE** or **--sets-mode** *NEW_MODE*
Change the current mode to *NEW_MODE* after this binding is executed
- ``-e`` or ``--erase`` Erase the binding with the given sequence and mode instead of defining a new one. Multiple sequences can be specified with this flag. Specifying ``-a`` or ``--all`` with ``-M`` or ``--mode`` erases all binds in the given mode regardless of sequence. Specifying ``-a`` or ``--all`` without ``-M`` or ``--mode`` erases all binds in all modes regardless of sequence.
**-e** or **--erase**
Erase the binding with the given sequence and mode instead of defining a new one.
Multiple sequences can be specified with this flag.
Specifying **-a** or **--all** with **-M** or **--mode** erases all binds in the given mode regardless of sequence.
Specifying **-a** or **--all** without **-M** or **--mode** erases all binds in all modes regardless of sequence.
- ``-a`` or ``--all`` See ``--erase`` and ``--key-names``
**-a** or **--all**
See **--erase** and **--key-names**
- ``--preset`` and ``--user`` specify if bind should operate on user or preset bindings. User bindings take precedence over preset bindings when fish looks up mappings. By default, all ``bind`` invocations work on the "user" level except for listing, which will show both levels. All invocations except for inserting new bindings can operate on both levels at the same time (if both ``--preset`` and ``--user`` are given). ``--preset`` should only be used in full binding sets (like when working on ``fish_vi_key_bindings``).
**--preset** and **--user**
Specify if bind should operate on user or preset bindings.
User bindings take precedence over preset bindings when fish looks up mappings.
By default, all ``bind`` invocations work on the "user" level except for listing, which will show both levels.
All invocations except for inserting new bindings can operate on both levels at the same time (if both **--preset** and **--user** are given).
**--preset** should only be used in full binding sets (like when working on ``fish_vi_key_bindings``).
**-h** or **--help**
Displays help about using this command.
Special input functions
-----------------------
The following special input functions are available:
- ``and``, only execute the next function if the previous succeeded (note: only some functions report success)
``and``
only execute the next function if the previous succeeded (note: only some functions report success)
- ``accept-autosuggestion``, accept the current autosuggestion completely
``accept-autosuggestion``
accept the current autosuggestion
- ``backward-char``, moves one character to the left
``backward-char``
move one character to the left.
If the completion pager is active, select the previous completion instead.
- ``backward-bigword``, move one whitespace-delimited word to the left
``backward-bigword``
move one whitespace-delimited word to the left
- ``backward-delete-char``, deletes one character of input to the left of the cursor
``backward-delete-char``
deletes one character of input to the left of the cursor
- ``backward-kill-bigword``, move the whitespace-delimited word to the left of the cursor to the killring
``backward-kill-bigword``
move the whitespace-delimited word to the left of the cursor to the killring
- ``backward-kill-line``, move everything from the beginning of the line to the cursor to the killring
``backward-kill-line``
move everything from the beginning of the line to the cursor to the killring
- ``backward-kill-path-component``, move one path component to the left of the cursor to the killring. A path component is everything likely to belong to a path component, i.e. not any of the following: `/={,}'\":@ |;<>&`, plus newlines and tabs.
``backward-kill-path-component``
move one path component to the left of the cursor to the killring. A path component is everything likely to belong to a path component, i.e. not any of the following: `/={,}'\":@ |;<>&`, plus newlines and tabs.
- ``backward-kill-word``, move the word to the left of the cursor to the killring. The "word" here is everything up to punctuation or whitespace.
``backward-kill-word``
move the word to the left of the cursor to the killring. The "word" here is everything up to punctuation or whitespace.
- ``backward-word``, move one word to the left
``backward-word``
move one word to the left
- ``beginning-of-buffer``, moves to the beginning of the buffer, i.e. the start of the first line
``beginning-of-buffer``
moves to the beginning of the buffer, i.e. the start of the first line
- ``beginning-of-history``, move to the beginning of the history
``beginning-of-history``
move to the beginning of the history
- ``beginning-of-line``, move to the beginning of the line
``beginning-of-line``
move to the beginning of the line
- ``begin-selection``, start selecting text
``begin-selection``
start selecting text
- ``cancel``, cancel the current commandline and replace it with a new empty one
``cancel``
cancel the current commandline and replace it with a new empty one
- ``cancel-commandline``, cancel the current commandline and replace it with a new empty one, leaving the old one in place with a marker to show that it was cancelled
``cancel-commandline``
cancel the current commandline and replace it with a new empty one, leaving the old one in place with a marker to show that it was cancelled
- ``capitalize-word``, make the current word begin with a capital letter
``capitalize-word``
make the current word begin with a capital letter
- ``complete``, guess the remainder of the current token
``complete``
guess the remainder of the current token
- ``complete-and-search``, invoke the searchable pager on completion options (for convenience, this also moves backwards in the completion pager)
``complete-and-search``
invoke the searchable pager on completion options (for convenience, this also moves backwards in the completion pager)
- ``delete-char``, delete one character to the right of the cursor
``delete-char``
delete one character to the right of the cursor
- ``delete-or-exit``, deletes one character to the right of the cursor or exits the shell if the commandline is empty.
``delete-or-exit``
delete one character to the right of the cursor, or exit the shell if the commandline is empty
- ``down-line``, move down one line
``down-line``
move down one line
- ``downcase-word``, make the current word lowercase
``downcase-word``
make the current word lowercase
- ``end-of-buffer``, moves to the end of the buffer, i.e. the end of the first line
``end-of-buffer``
moves to the end of the buffer, i.e. the end of the first line
- ``end-of-history``, move to the end of the history
``end-of-history``
move to the end of the history
- ``end-of-line``, move to the end of the line
``end-of-line``
move to the end of the line
- ``end-selection``, end selecting text
``end-selection``
end selecting text
- ``expand-abbr``, expands any abbreviation currently under the cursor
``expand-abbr``
expands any abbreviation currently under the cursor
- ``execute``, run the current commandline
``execute``
run the current commandline
- ``exit``, exit the shell
``exit``
exit the shell
- ``forward-bigword``, move one whitespace-delimited word to the right
``forward-bigword``
move one whitespace-delimited word to the right
- ``forward-char``, move one character to the right
``forward-char``
move one character to the right; or if at the end of the commandline, accept the current autosuggestion.
If the completion pager is active, select the next completion instead.
- ``forward-single-char``, move one character to the right; if an autosuggestion is available, only take a single char from it
``forward-single-char``
move one character to the right; or if at the end of the commandline, accept a single char from the current autosuggestion.
- ``forward-word``, move one word to the right
``forward-word``
move one word to the right; or if at the end of the commandline, accept one word
from the current autosuggestion.
- ``history-search-backward``, search the history for the previous match
``history-search-backward``
search the history for the previous match
- ``history-search-forward``, search the history for the next match
``history-search-forward``
search the history for the next match
- ``history-prefix-search-backward``, search the history for the previous prefix match
``history-prefix-search-backward``
search the history for the previous prefix match
- ``history-prefix-search-forward``, search the history for the next prefix match
``history-prefix-search-forward``
search the history for the next prefix match
- ``history-token-search-backward``, search the history for the previous matching argument
``history-token-search-backward``
search the history for the previous matching argument
- ``history-token-search-forward``, search the history for the next matching argument
``history-token-search-forward``
search the history for the next matching argument
- ``forward-jump`` and ``backward-jump``, read another character and jump to its next occurence after/before the cursor
``forward-jump`` and ``backward-jump``
read another character and jump to its next occurence after/before the cursor
- ``forward-jump-till`` and ``backward-jump-till``, jump to right *before* the next occurence
``forward-jump-till`` and ``backward-jump-till``
jump to right *before* the next occurence
- ``repeat-jump`` and ``repeat-jump-reverse``, redo the last jump in the same/opposite direction
``repeat-jump`` and ``repeat-jump-reverse``
redo the last jump in the same/opposite direction
- ``kill-bigword``, move the next whitespace-delimited word to the killring
``kill-bigword``
move the next whitespace-delimited word to the killring
- ``kill-line``, move everything from the cursor to the end of the line to the killring
``kill-line``
move everything from the cursor to the end of the line to the killring
- ``kill-selection``, move the selected text to the killring
``kill-selection``
move the selected text to the killring
- ``kill-whole-line``, move the line to the killring
``kill-whole-line``
move the line to the killring
- ``kill-word``, move the next word to the killring
``kill-word``
move the next word to the killring
- ``or``, only execute the next function if the previous succeeded (note: only some functions report success)
``nextd-or-forward-word``
if the commandline is empty, then move forward in the directory history, otherwise move one word to the right;
or if at the end of the commandline, accept one word from the current autosuggestion.
- ``pager-toggle-search``, toggles the search field if the completions pager is visible.
``or``
only execute the next function if the previous succeeded (note: only some functions report success)
- ``repaint``, reexecutes the prompt functions and redraws the prompt (also ``force-repaint`` for backwards-compatibility)
``pager-toggle-search``
toggles the search field if the completions pager is visible.
- ``repaint-mode``, reexecutes the :ref:`fish_mode_prompt <cmd-fish_mode_prompt>` and redraws the prompt. This is useful for vi-mode. If no ``fish_mode_prompt`` exists or it prints nothing, it acts like a normal repaint.
``prevd-or-backward-word``
if the commandline is empty, then move backward in the directory history, otherwise move one word to the left
- ``self-insert``, inserts the matching sequence into the command line
``repaint``
reexecutes the prompt functions and redraws the prompt (also ``force-repaint`` for backwards-compatibility)
- ``self-insert-notfirst``, inserts the matching sequence into the command line, unless the cursor is at the beginning
``repaint-mode``
reexecutes the :ref:`fish_mode_prompt <cmd-fish_mode_prompt>` and redraws the prompt. This is useful for vi-mode. If no ``fish_mode_prompt`` exists or it prints nothing, it acts like a normal repaint.
- ``suppress-autosuggestion``, remove the current autosuggestion. Returns true if there was a suggestion to remove.
``self-insert``
inserts the matching sequence into the command line
- ``swap-selection-start-stop``, go to the other end of the highlighted text without changing the selection
``self-insert-notfirst``
inserts the matching sequence into the command line, unless the cursor is at the beginning
- ``transpose-chars``, transpose two characters to the left of the cursor
``suppress-autosuggestion``
remove the current autosuggestion. Returns true if there was a suggestion to remove.
- ``transpose-words``, transpose two words to the left of the cursor
``swap-selection-start-stop``
go to the other end of the highlighted text without changing the selection
- ``togglecase-char``, toggle the capitalisation (case) of the character under the cursor
``transpose-chars``
transpose two characters to the left of the cursor
- ``togglecase-selection``, toggle the capitalisation (case) of the selection
``transpose-words``
transpose two words to the left of the cursor
- ``insert-line-under``, add a new line under the current line
``togglecase-char``
toggle the capitalisation (case) of the character under the cursor
- ``insert-line-over``, add a new line over the current line
``togglecase-selection``
toggle the capitalisation (case) of the selection
- ``up-line``, move up one line
``insert-line-under``
add a new line under the current line
- ``undo`` and ``redo``, revert or redo the most recent edits on the command line
``insert-line-over``
add a new line over the current line
- ``upcase-word``, make the current word uppercase
``up-line``
move up one line
- ``yank``, insert the latest entry of the killring into the buffer
``undo`` and ``redo``
revert or redo the most recent edits on the command line
- ``yank-pop``, rotate to the previous entry of the killring
``upcase-word``
make the current word uppercase
``yank``
insert the latest entry of the killring into the buffer
``yank-pop``
rotate to the previous entry of the killring
Additional functions
--------------------
The following functions are included as normal functions, but are particularly useful for input editing:
- ``up-or-search`` and ``down-or-search``, which move the cursor or search the history depending on the cursor position and current mode
``up-or-search`` and ``down-or-search``
move the cursor or search the history depending on the cursor position and current mode
- ``edit_command_buffer``, open the visual editor (controlled by the ``VISUAL`` or ``EDITOR`` environment variables) with the current command-line contents
``edit_command_buffer``
open the visual editor (controlled by the :envvar:`VISUAL` or :envvar:`EDITOR` environment variables) with the current command-line contents
- ``delete-or-exit``, quit the shell if the current command-line is empty, or delete the character under the cursor if not
``fish_clipboard_copy``
copy the current selection to the system clipboard
- ``fish_clipboard_copy``, copy the current selection to the system clipboard
``fish_clipboard_paste``
paste the current selection from the system clipboard before the cursor
- ``fish_clipboard_paste``, paste the current selection from the system clipboard before the cursor
``fish_commandline_append``
append the argument to the command-line. If the command-line already ends with the argument, this removes the suffix instead. Starts with the last command from history if the command-line is empty.
- ``fish_commandline_append``, append the argument to the command-line. If the command-line already ends with the argument, this removes the suffix instead. Starts with the last command from history if the command-line is empty.
- ``fish_commandline_prepend``, prepend the argument to the command-line. If the command-line already starts with the argument, this removes the prefix instead. Starts with the last command from history if the command-line is empty.
``fish_commandline_prepend``
prepend the argument to the command-line. If the command-line already starts with the argument, this removes the prefix instead. Starts with the last command from history if the command-line is empty.
Examples
--------

25
doc_src/cmds/block.rst
View File

@ -6,10 +6,10 @@ block - temporarily block delivery of events
Synopsis
--------
::
block [OPTIONS...]
.. synopsis::
block [(--local | --global)]
block --erase
Description
-----------
@ -22,18 +22,24 @@ The block can be removed. Any events which triggered while the block was in plac
Event blocks should not be confused with code blocks, which are created with ``begin``, ``if``, ``while`` or ``for``
The following parameters are available:
Without options, the ``block`` command acts with function scope.
- ``-l`` or ``--local`` Release the block automatically at the end of the current innermost code block scope
The following options are available:
- ``-g`` or ``--global`` Never automatically release the lock
**-l** or **--local**
Release the block automatically at the end of the current innermost code block scope.
- ``-e`` or ``--erase`` Release global block
**-g** or **--global**
Never automatically release the lock.
**-e** or **--erase**
Release global block.
**-h** or **--help**
Displays help about using this command.
Example
-------
::
# Create a function that listens for events
@ -48,8 +54,7 @@ Example
block -e
# 'foo fired' will now be printed
Notes
-----
Note that events are only received from the current fish process as there is no way to send events from one fish process to another.
Events are only received from the current fish process as there is no way to send events from one fish process to another (yet).

12
doc_src/cmds/break.rst
View File

@ -6,19 +6,21 @@ break - stop the current inner loop
Synopsis
--------
::
LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end
.. synopsis::
LOOP_CONSTRUCT
[COMMANDS ...]
break
[COMMANDS ...]
end
Description
-----------
``break`` halts a currently running loop, such as a :ref:`switch <cmd-switch>`, :ref:`for <cmd-for>` or :ref:`while <cmd-while>` loop. It is usually added inside of a conditional block such as an :ref:`if <cmd-if>` block.
``break`` halts a currently running loop (*LOOP_CONSTRUCT*), such as a :ref:`switch <cmd-switch>`, :ref:`for <cmd-for>` or :ref:`while <cmd-while>` loop. It is usually added inside of a conditional block such as an :ref:`if <cmd-if>` block.
There are no parameters for ``break``.
Example
-------
The following code searches all .c files for "smurf", and halts at the first occurrence.

3
doc_src/cmds/breakpoint.rst
View File

@ -6,11 +6,10 @@ breakpoint - launch debug mode
Synopsis
--------
::
.. synopsis::
breakpoint
Description
-----------

22
doc_src/cmds/builtin.rst
View File

@ -6,27 +6,31 @@ builtin - run a builtin command
Synopsis
--------
::
.. synopsis::
builtin [OPTIONS...] BUILTINNAME
builtin --query BUILTINNAMES...
builtin [OPTIONS] BUILTINNAME
builtin --query BUILTINNAME ...
builtin --names
Description
-----------
``builtin`` forces the shell to use a builtin command, rather than a function or program.
``builtin`` forces the shell to use a builtin command named *BUILTIN*, rather than a function or external program.
The following parameters are available:
The following options are available:
- ``-n`` or ``--names`` List the names of all defined builtins
- ``-q`` or ``--query`` tests if any of the specified builtins exists
**-n** or **--names**
Lists the names of all defined builtins.
**-q** or **--query** *BUILTIN*
Tests if any of the specified builtins exist.
**-h** or **--help**
Displays help about using this command.
Example
-------
::
builtin jobs

7
doc_src/cmds/case.rst
View File

@ -6,9 +6,12 @@ case - conditionally execute a block of commands
Synopsis
--------
::
.. synopsis::
switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
switch VALUE
[case [GLOB ...]
[COMMAND ...]]
end
Description
-----------

16
doc_src/cmds/cd.rst
View File

@ -6,7 +6,7 @@ cd - change directory
Synopsis
--------
::
.. synopsis::
cd [DIRECTORY]
@ -14,16 +14,22 @@ Description
-----------
``cd`` changes the current working directory.
If ``DIRECTORY`` is given, it will become the new directory. If no parameter is given, the ``$HOME`` environment variable will be used.
If *DIRECTORY* is given, it will become the new directory. If no parameter is given, the :envvar:`HOME` environment variable will be used.
If ``DIRECTORY`` is a relative path, all the paths in the ``$CDPATH`` will be tried as prefixes for it, in addition to ``$PWD``. It is recommended to keep ``.`` as the first element of ``$CDPATH``, or ``$PWD`` will be tried last.
If *DIRECTORY* is a relative path, all the paths in the :envvar:`CDPATH` will be tried as prefixes for it, in addition to :envvar:`PWD`.
It is recommended to keep **.** as the first element of :envvar:`CDPATH`, or :envvar:`PWD` will be tried last.
Fish will also try to change directory if given a command that looks like a directory (starting with ``.``, ``/`` or ``~``, or ending with ``/``), without explicitly requiring ``cd``.
Fish will also try to change directory if given a command that looks like a directory (starting with **.**, **/** or **~**, or ending with **/**), without explicitly requiring **cd**.
Fish also ships a wrapper function around the builtin ``cd`` that understands ``cd -`` as changing to the previous directory. See also :ref:`prevd <cmd-prevd>`. This wrapper function maintains a history of the 25 most recently visited directories in the ``$dirprev`` and ``$dirnext`` global variables. If you make those universal variables your ``cd`` history is shared among all fish instances.
Fish also ships a wrapper function around the builtin **cd** that understands ``cd -`` as changing to the previous directory.
See also :ref:`prevd <cmd-prevd>`.
This wrapper function maintains a history of the 25 most recently visited directories in the ``$dirprev`` and ``$dirnext`` global variables.
If you make those universal variables your **cd** history is shared among all fish instances.
As a special case, ``cd .`` is equivalent to ``cd $PWD``, which is useful in cases where a mountpoint has been recycled or a directory has been removed and recreated.
The **--help** or **-h** option displays help about using this command, and does not change the directory.
Examples
--------

13
doc_src/cmds/cdh.rst
View File

@ -6,16 +6,21 @@ cdh - change to a recently visited directory
Synopsis
--------
::
.. synopsis::
cdh [ directory ]
cdh [DIRECTORY]
Description
-----------
``cdh`` with no arguments presents a list of :ref:`recently visited directories <directory-history>`. You can then select one of the entries by letter or number. You can also press :kbd:`Tab` to use the completion pager to select an item from the list. If you give it a single argument it is equivalent to ``cd directory``.
``cdh`` with no arguments presents a list of :ref:`recently visited directories <directory-history>`.
You can then select one of the entries by letter or number.
You can also press :kbd:`Tab` to use the completion pager to select an item from the list.
If you give it a single argument it is equivalent to ``cd DIRECTORY``.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates. If you make those universal variables your ``cd`` history is shared among all fish instances.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories.
The history is stored in the :envvar:`dirprev` and :envvar:`$dirnext` variables, which this command manipulates.
If you make those universal variables, your ``cd`` history is shared among all fish instances.
See Also
--------

30
doc_src/cmds/command.rst
View File

@ -6,32 +6,36 @@ command - run a program
Synopsis
--------
::
.. synopsis::
command [OPTIONS] COMMANDNAME [ARGS...]
command [OPTIONS] [COMMANDNAME [ARG ...]]
Description
-----------
``command`` forces the shell to execute the program ``COMMANDNAME`` and ignore any functions or builtins with the same name.
**command** forces the shell to execute the program *COMMANDNAME* and ignore any functions or builtins with the same name.
The following options are available:
- ``-a`` or ``--all`` returns all the external COMMANDNAMEs that are found in ``$PATH`` in the order they are found.
**-a** or **--all**
Prints all *COMMAND* found in :envvar:`PATH`, in the order found.
- ``-q`` or ``--query``, silences the output and prints nothing, setting only the exit status. Implies ``--search``. For compatibility with old fish versions this is also ``--quiet`` (but this is deprecated).
**-q** or **--query**
Silence output and print nothing, setting only exit status.
Implies **--search**.
For compatibility, this is also **--quiet** (deprecated).
- ``-s`` or ``--search`` returns the name of the external command that would be executed, or nothing if no file with the specified name could be found in the ``$PATH``.
**-v** (or **-s** or **--search**)
Prints the external command that would be executed, or prints nothing if no file with the specified name could be found in :envvar:`PATH`.
With the ``-s`` option, ``command`` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found. Additionally passing a ``-q`` or ``--quiet`` option prevents any paths from being printed, like ``type -q``, for testing only the exit status.
**-h** or **--help**
Displays help about using this command.
For basic compatibility with POSIX ``command``, the ``-v`` flag is recognized as an alias for ``-s``.
With the **-v** option, ``command`` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 127 if no commands could be found. **--quiet** used with **-v** prevents commands being printed, like ``type -q``.
Examples
--------
``command ls`` causes fish to execute the ``ls`` program, even if an ``ls`` function exists.
``command -s ls`` returns the path to the ``ls`` program.
``command -q git; and command git log`` runs ``git log`` only if ``git`` exists.
| ``command ls`` executes the ``ls`` program, even if an ``ls`` function also exists.
| ``command -s ls`` prints the path to the ``ls`` program.
| ``command -q git; and command git log`` runs ``git log`` only if ``git`` exists.

68
doc_src/cmds/commandline.rst
View File

@ -6,7 +6,7 @@ commandline - set or get the current command line buffer
Synopsis
--------
::
.. synopsis::
commandline [OPTIONS] [CMD]
@ -17,51 +17,81 @@ Description
With no parameters, ``commandline`` returns the current value of the command line.
With ``CMD`` specified, the command line buffer is erased and replaced with the contents of ``CMD``.
With **CMD** specified, the command line buffer is erased and replaced with the contents of **CMD**.
The following options are available:
- ``-C`` or ``--cursor`` set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position. If one of the options ``-j``, ``-p`` or ``-t`` is given, the position is relative to the respective substring instead of the entire command line buffer.
**-C** or **--cursor**
Set or get the current cursor position, not the contents of the buffer.
If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position.
If one of the options **-j**, **-p** or **-t** is given, the position is relative to the respective substring instead of the entire command line buffer.
- ``-f`` or ``--function`` causes any additional arguments to be interpreted as input functions, and puts them into the queue, so that they will be read before any additional actual key presses are. This option cannot be combined with any other option. See :ref:`bind <cmd-bind>` for a list of input functions.
**-f** or **--function**
Causes any additional arguments to be interpreted as input functions, and puts them into the queue, so that they will be read before any additional actual key presses are.
This option cannot be combined with any other option.
See :ref:`bind <cmd-bind>` for a list of input functions.
**-h** or **--help**
Displays help about using this command.
The following options change the way ``commandline`` updates the command line buffer:
- ``-a`` or ``--append`` do not remove the current commandline, append the specified string at the end of it
**-a** or **--append**
Do not remove the current commandline, append the specified string at the end of it.
- ``-i`` or ``--insert`` do not remove the current commandline, insert the specified string at the current cursor position
**-i** or **--insert**
Do not remove the current commandline, insert the specified string at the current cursor position
- ``-r`` or ``--replace`` remove the current commandline and replace it with the specified string (default)
**-r** or **--replace**
Remove the current commandline and replace it with the specified string (default)
The following options change what part of the commandline is printed or updated:
- ``-b`` or ``--current-buffer`` select the entire commandline, not including any displayed autosuggestion (default)
**-b** or **--current-buffer**
Select the entire commandline, not including any displayed autosuggestion (default).
- ``-j`` or ``--current-job`` select the current job - a `job` here is one pipeline. It stops at logical operators or terminators (``;``, ``&`` or newlines).
**-j** or **--current-job**
Select the current job - a **job** here is one pipeline.
Stops at logical operators or terminators (**;**, **&**, and newlines).
- ``-p`` or ``--current-process`` select the current process - a `process` here is one simple command. It stops at logical operators, terminators or pipes.
**-p** or **--current-process**
Select the current process - a **process** here is one command.
Stops at logical operators, terminators, and pipes.
- ``-s`` or ``--current-selection`` selects the current selection
**-s** or **--current-selection**
Selects the current selection
- ``-t`` or ``--current-token`` select the current token
**-t** or **--current-token**
Selects the current token
The following options change the way ``commandline`` prints the current commandline buffer:
- ``-c`` or ``--cut-at-cursor`` only print selection up until the current cursor position
**-c** or **--cut-at-cursor**
Only print selection up until the current cursor position.
- ``-o`` or ``--tokenize`` tokenize the selection and print one string-type token per line
**-o** or **--tokenize**
Tokenize the selection and print one string-type token per line.
If ``commandline`` is called during a call to complete a given string using ``complete -C STRING``, ``commandline`` will consider the specified string to be the current contents of the command line.
The following options output metadata about the commandline state:
- ``-L`` or ``--line`` print the line that the cursor is on, with the topmost line starting at 1
**-L** or **--line**
Print the line that the cursor is on, with the topmost line starting at 1.
- ``-S`` or ``--search-mode`` evaluates to true if the commandline is performing a history search
**-S** or **--search-mode**
Evaluates to true if the commandline is performing a history search.
- ``-P`` or ``--paging-mode`` evaluates to true if the commandline is showing pager contents, such as tab completions
**-P** or **--paging-mode**
Evaluates to true if the commandline is showing pager contents, such as tab completions.
- ``--is-valid`` returns true when the commandline is syntactically valid and complete. If it is, it would be executed when the ``execute`` bind function is called. If the commandline is incomplete, it returns 2, if it is erroneus, it returns 1.
**--paging-full-mode**
Evaluates to true if the commandline is showing pager contents, such as tab completions and all lines are shown (no "<n> more rows" message).
**--is-valid**
Returns true when the commandline is syntactically valid and complete.
If it is, it would be executed when the ``execute`` bind function is called.
If the commandline is incomplete, return 2, if erroneus, return 1.
Example
-------
@ -82,7 +112,7 @@ The ``echo $flounder >&`` is the first process, ``less`` the second and ``and ec
``echo $flounder >&2 | less`` is the first job, ``and echo $catfish`` the second.
``$flounder`` is the current token.
**$flounder** is the current token.
More examples:

72
doc_src/cmds/complete.rst
View File

@ -6,23 +6,10 @@ complete - edit command specific tab-completions
Synopsis
--------
::
.. synopsis::
complete [( -c | --command | -p | --path )] COMMAND
[( -c | --command | -p | --path ) COMMAND]...
[( -e | --erase )]
[( -s | --short-option ) SHORT_OPTION]...
[( -l | --long-option | -o | --old-option ) LONG_OPTION]...
[( -a | --arguments ) ARGUMENTS]
[( -k | --keep-order )]
[( -f | --no-files )]
[( -F | --force-files )]
[( -r | --require-parameter )]
[( -x | --exclusive )]
[( -w | --wraps ) WRAPPED_COMMAND]...
[( -n | --condition ) CONDITION]
[( -d | --description ) DESCRIPTION]
complete ( -C [STRING] | --do-complete[=STRING] )
complete ((-c | --command) | (-p | --path)) COMMAND [OPTIONS]
complete (-C | --do-complete) [--escape] STRING
Description
-----------
@ -32,35 +19,58 @@ Description
For an introduction to writing your own completions, see :ref:`Writing your own completions <completion-own>` in
the fish manual.
- ``-c COMMAND`` or ``--command COMMAND`` specifies that ``COMMAND`` is the name of the command. If there is no ``-c`` or ``-p``, one non-option argument will be used as the command.
The following options are available:
- ``-p COMMAND`` or ``--path COMMAND`` specifies that ``COMMAND`` is the absolute path of the command (optionally containing wildcards).
**-c** or **--command** *COMMAND*
Specifies that *COMMAND* is the name of the command. If there is no **-c** or **-p**, one non-option argument will be used as the command.
- ``-e`` or ``--erase`` deletes the specified completion.
**-p** or **--path** *COMMAND*
Specifies that *COMMAND* is the absolute path of the command (optionally containing wildcards).
- ``-s SHORT_OPTION`` or ``--short-option=SHORT_OPTION`` adds a short option to the completions list.
**-e** or **--erase**
Deletes the specified completion.
- ``-l LONG_OPTION`` or ``--long-option=LONG_OPTION`` adds a GNU style long option to the completions list.
**-s** or **--short-option** *SHORT_OPTION*
Adds a short option to the completions list.
- ``-o LONG_OPTION`` or ``--old-option=LONG_OPTION`` adds an old style long option to the completions list (See below for details).
**-l** or **--long-option** *LONG_OPTION*
Adds a GNU style long option to the completions list.
- ``-a ARGUMENTS`` or ``--arguments=ARGUMENTS`` adds the specified option arguments to the completions list.
**-o** or **--old-option** *LONG_OPTION*
Adds an old style long option to the completions list (see below for details).
- ``-k`` or ``--keep-order`` keeps the order of ``ARGUMENTS`` instead of sorting alphabetically. Multiple ``complete`` calls with ``-k`` result in arguments of the later ones displayed first.
**-a** or **--arguments** *ARGUMENTS*
Adds the specified option arguments to the completions list.
- ``-f`` or ``--no-files`` says that this completion may not be followed by a filename.
**-k** or **--keep-order**
Keeps the order of *ARGUMENTS* instead of sorting alphabetically. Multiple ``complete`` calls with **-k** result in arguments of the later ones displayed first.
- ``-F`` or ``--force-files`` says that this completion may be followed by a filename, even if another applicable ``complete`` specified ``--no-files``.
**-f** or **--no-files**
This completion may not be followed by a filename.
- ``-r`` or ``--require-parameter`` says that this completion must have an option argument, i.e. may not be followed by another option.
**-F** or **--force-files**
This completion may be followed by a filename, even if another applicable ``complete`` specified **--no-files**.
- ``-x`` or ``--exclusive`` is short for ``-r`` and ``-f``.
**-r** or **--require-parameter**
This completion must have an option argument, i.e. may not be followed by another option.
- ``-w WRAPPED_COMMAND`` or ``--wraps=WRAPPED_COMMAND`` causes the specified command to inherit completions from the wrapped command (See below for details).
**-x** or **--exclusive**
Short for **-r** and **-f**.
- ``-n CONDITION`` or ``--condition CONDITION`` specifies that this completion should only be used if the CONDITION (a shell command) returns 0. This makes it possible to specify completions that should only be used in some cases.
**-w** or **--wraps** *WRAPPED_COMMAND*
Causes the specified command to inherit completions from *WRAPPED_COMMAND* (see below for details).
- ``-C STRING`` or ``--do-complete=STRING`` makes complete try to find all possible completions for the specified string. If there is no STRING, the current commandline is used instead.
**-n** or **--condition** *CONDITION*
This completion should only be used if the *CONDITION* (a shell command) returns 0. This makes it possible to specify completions that should only be used in some cases.
**-C** or **--do-complete** *STRING*
Makes ``complete`` try to find all possible completions for the specified string. If there is no *STRING*, the current commandline is used instead.
**--escape**
When used with ``-C``, escape special characters in completions.
**-h** or **--help**
Displays help about using this command.
Command specific tab-completions in ``fish`` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as ``-h``, ``-help`` or ``--help``. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU getopt library. These styles are:

32
doc_src/cmds/contains.rst
View File

@ -6,27 +6,32 @@ contains - test if a word is present in a list
Synopsis
--------
::
.. synopsis::
contains [OPTIONS] KEY [VALUES...]
contains [OPTIONS] KEY [VALUES ...]
Description
-----------
``contains`` tests whether the set ``VALUES`` contains the string ``KEY``. If so, ``contains`` exits with status 0; if not, it exits with status 1.
``contains`` tests whether the set *VALUES* contains the string *KEY*.
If so, ``contains`` exits with code 0; if not, it exits with code 1.
The following options are available:
- ``-i`` or ``--index`` print the word index
**-i** or **--index**
Print the index (number of the element in the set) of the first matching element.
Note that, like GNU tools and most of fish's builtins, ``contains`` interprets all arguments starting with a ``-`` as options to contains, until it reaches an argument that is ``--`` (two dashes). See the examples below.
**-h** or **--help**
Displays help about using this command.
Note that ``contains`` interprets all arguments starting with a **-** as an option to ``contains``, until an **--** argument is reached.
See the examples below.
Example
-------
If $animals is a list of animals, the following will test if it contains a cat:
If *animals* is a list of animals, the following will test if *animals* contains "cat":
::
@ -35,9 +40,7 @@ If $animals is a list of animals, the following will test if it contains a cat:
end
This code will add some directories to $PATH if they aren't yet included:
This code will add some directories to :envvar:`PATH` if they aren't yet included:
::
@ -48,9 +51,7 @@ This code will add some directories to $PATH if they aren't yet included:
end
While this will check if ``hasargs`` was run with the ``-q`` option:
While this will check if function ``hasargs`` is being ran with the **-q** option:
::
@ -61,4 +62,5 @@ While this will check if ``hasargs`` was run with the ``-q`` option:
end
The ``--`` here stops ``contains`` from treating ``-q`` to an option to itself. Instead it treats it as a normal string to check.
The **--** here stops ``contains`` from treating **-q** to an option to itself.
Instead it treats it as a normal string to check.

4
doc_src/cmds/continue.rst
View File

@ -6,9 +6,9 @@ continue - skip the remainder of the current iteration of the current inner loop
Synopsis
--------
::
.. synopsis::
LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end
LOOP_CONSTRUCT; [COMMANDS ...;] continue; [COMMANDS ...;] end
Description
-----------

6
doc_src/cmds/count.rst
View File

@ -6,11 +6,11 @@ count - count the number of elements of a list
Synopsis
--------
::
.. synopsis::
count $VARIABLE
count STRING1 STRING2 ...
COMMAND | count
count < FILE
count [...] < FILE
Description
-----------

2
doc_src/cmds/dirh.rst
View File

@ -6,7 +6,7 @@ dirh - print directory history
Synopsis
--------
::
.. synopsis::
dirh

17
doc_src/cmds/dirs.rst
View File

@ -6,21 +6,26 @@ dirs - print directory stack
Synopsis
--------
::
.. synopsis::
dirs
dirs -c
dirs [-c]
Description
-----------
``dirs`` prints the current :ref:`directory stack <directory-stack>`, as created by :ref:`pushd <cmd-pushd>` and modified by :ref:`popd <cmd-popd>`.
With "-c", it clears the directory stack instead.
The following options are available:
``dirs`` does not accept any parameters.
**-c**:
Clear the directory stack instead of printing it.
**-h** or **--help**
Displays help about using this command.
``dirs`` does not accept any arguments.
See Also
--------
- the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.
- the :ref:`cdh <cmd-cdh>` command, which provides a more intuitive way to navigate to recently visited directories.

6
doc_src/cmds/disown.rst
View File

@ -6,9 +6,9 @@ disown - remove a process from the list of jobs
Synopsis
--------
::
.. synopsis::
disown [ PID ... ]
disown [PID ...]
Description
-----------
@ -23,6 +23,8 @@ If a job is stopped, it is sent a signal to continue running, and a warning is p
``disown`` returns 0 if all specified jobs were disowned successfully, and 1 if any problems were encountered.
The **--help** or **-h** option displays help about using this command.
Example
-------

16
doc_src/cmds/echo.rst
View File

@ -6,24 +6,28 @@ echo - display a line of text
Synopsis
--------
::
.. synopsis::
echo [OPTIONS] [STRING]
Description
-----------
``echo`` displays a string of text.
``echo`` displays *STRING* of text.
The following options are available:
- ``-n``, Do not output a newline
- **-n**
Do not output a newline.
- ``-s``, Do not separate arguments with spaces
**-s**
Do not separate arguments with spaces.
- ``-E``, Disable interpretation of backslash escapes (default)
**-E**
Disable interpretation of backslash escapes (default).
- ``-e``, Enable interpretation of backslash escapes
**-e**
Enable interpretation of backslash escapes.
Unlike other shells, this echo accepts ``--`` to signal the end of the options.

12
doc_src/cmds/else.rst
View File

@ -6,22 +6,22 @@ else - execute command if a condition is not met
Synopsis
--------
::
.. synopsis::
if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
if CONDITION; COMMANDS_TRUE ...; [else; COMMANDS_FALSE ...;] end
Description
-----------
:ref:`if <cmd-if>` will execute the command ``CONDITION``. If the condition's exit status is 0, the commands ``COMMANDS_TRUE`` will execute. If it is not 0 and ``else`` is given, ``COMMANDS_FALSE`` will be executed.
:ref:`if <cmd-if>` will execute the command *CONDITION**.
If the condition's exit status is 0, the commands *COMMANDS_TRUE* will execute.
If it is not 0 and **else** is given, *COMMANDS_FALSE* will be executed.
Example
-------
The following code tests whether a file ``foo.txt`` exists as a regular file.
The following code tests whether a file *foo.txt* exists as a regular file.
::

5
doc_src/cmds/emit.rst
View File

@ -6,15 +6,16 @@ emit - emit a generic event
Synopsis
--------
::
.. synopsis::
emit EVENT_NAME [ARGUMENTS...]
emit EVENT_NAME [ARGUMENTS ...]
Description
-----------
``emit`` emits, or fires, an event. Events are delivered to, or caught by, special functions called :ref:`event handlers <event>`. The arguments are passed to the event handlers as function arguments.
The **--help** or **-h** option displays help about using this command.
Example
-------

24
doc_src/cmds/end.rst
View File

@ -6,23 +6,29 @@ end - end a block of commands
Synopsis
--------
::
.. synopsis::
begin; [COMMANDS...] end
function NAME [OPTIONS]; COMMANDS...; end
if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
while CONDITION; COMMANDS...; end
for VARNAME in [VALUES...]; COMMANDS...; end
begin
[COMMANDS ...]
end
.. synopsis::
function NAME [OPTIONS]; COMMANDS ...; end
if CONDITION; COMMANDS_TRUE ...; [else; COMMANDS_FALSE ...;] end
switch VALUE; [case [WILDCARD ...]; [COMMANDS ...]; ...] end
while CONDITION; COMMANDS ...; end
for VARNAME in [VALUES ...]; COMMANDS ...; end
Description
-----------
``end`` ends a block of commands started by one of the following commands:
The **end** keyword ends a block of commands started by one of the following commands:
- :ref:`begin <cmd-begin>` to start a block of commands
- :ref:`function <cmd-function>` to define a function
- :ref:`if <cmd-if>`, :ref:`switch <cmd-switch>` to conditionally execute commands
- :ref:`while <cmd-while>`, :ref:`for <cmd-for>` to perform commands multiple times
The ``end`` command does not change the current exit status. Instead, the status after it will be the status returned by the most recent command.
The **end** keyword does not change the current exit status.
Instead, the status after it will be the status returned by the most recent command.

12
doc_src/cmds/eval.rst
View File

@ -6,20 +6,19 @@ eval - evaluate the specified commands
Synopsis
--------
::
eval [COMMANDS...]
.. synopsis::
eval [COMMANDS ...]
Description
-----------
``eval`` evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator.
**eval** evaluates the specified parameters as a command.
If more than one parameter is specified, all parameters will be joined using a space character as a separator.
If your command does not need access to stdin, consider using :ref:`source <cmd-source>` instead.
If the command does not need access to stdin, consider using :ref:`source <cmd-source>` instead.
If no piping or other compound shell constructs are required, variable-expansion-as-command, as in ``set cmd ls -la; $cmd``, is also an option.
Example
-------
@ -30,4 +29,3 @@ The following code will call the ls command and truncate each filename to the fi
set cmd ls \| cut -c 1-12
eval $cmd

5
doc_src/cmds/exec.rst
View File

@ -6,15 +6,16 @@ exec - execute command in current process
Synopsis
--------
::
.. synopsis::
exec COMMAND [OPTIONS...]
exec COMMAND
Description
-----------
``exec`` replaces the currently running shell with a new command. On successful completion, ``exec`` never returns. ``exec`` cannot be used inside a pipeline.
The **--help** or **-h** option displays help about using this command.
Example
-------

8
doc_src/cmds/exit.rst
View File

@ -7,12 +7,16 @@ exit - exit the shell
Synopsis
--------
**exit** [*code*]
.. synopsis::
exit [CODE]
Description
-----------
``exit`` is a special builtin that causes the shell to exit. Either 255 or the *code* supplied is used, whichever is lesser.
**exit** is a special builtin that causes the shell to exit. Either 255 or the *CODE* supplied is used, whichever is lesser.
Otherwise, the exit status will be that of the last command executed.
If exit is called while sourcing a file (using the :ref:`source <cmd-source>` builtin) the rest of the file will be skipped, but the shell itself will not exit.
The **--help** or **-h** option displays help about using this command.

4
doc_src/cmds/false.rst
View File

@ -6,7 +6,9 @@ false - return an unsuccessful result
Synopsis
--------
**false**
.. synopsis::
false
Description
-----------

12
doc_src/cmds/fg.rst
View File

@ -6,16 +6,22 @@ fg - bring job to foreground
Synopsis
--------
::
.. synopsis::
fg [PID]
Description
-----------
``fg`` brings the specified :ref:`job <syntax-job-control>` to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If ``PID`` is specified, the job containing a process with the specified process ID is put in the foreground.
The **fg** builtin brings the specified :ref:`job <syntax-job-control>` to the foreground, resuming it if it is stopped.
While a foreground job is executed, fish is suspended.
If no job is specified, the last job to be used is put in the foreground.
If ``PID`` is specified, the job containing a process with the specified process ID is put in the foreground.
For compatibility with other shells, job expansion syntax is supported for ``fg``. A ``PID`` of the format ``%1`` will foreground job 1. Job numbers can be seen in the output of :ref:`jobs <cmd-jobs>`.
For compatibility with other shells, job expansion syntax is supported for ``fg``. A *PID* of the format **%1** will foreground job 1.
Job numbers can be seen in the output of :ref:`jobs <cmd-jobs>`.
The **--help** or **-h** option displays help about using this command.
Example
-------

67
doc_src/cmds/fish.rst
View File

@ -7,9 +7,10 @@ fish - the friendly interactive shell
Synopsis
--------
**fish** [*OPTIONS*] [*FILE* [*ARGS* ...]]
.. synopsis::
**fish** [*OPTIONS*] [**-c** *COMMAND* [*ARGS* ...]]
fish [OPTIONS] [FILE [ARG ...]]
fish [OPTIONS] [-c COMMAND [ARG ...]]
Description
-----------
@ -22,39 +23,55 @@ The :ref:`tutorial <tutorial>` is available as HTML via ``help tutorial`` or in
The following options are available:
- ``-c`` or ``--command=COMMANDS`` evaluate the specified commands instead of reading from the commandline, passing any additional positional arguments via ``$argv``.
Note that, unlike other shells, the first argument is *not* the name of the program ``$0``, but simply the first normal argument.
**-c** or **--command=COMMAND**
Evaluate the specified commands instead of reading from the commandline, passing additional positional arguments through ``$argv``.
- ``-C`` or ``--init-command=COMMANDS`` evaluate the specified commands after reading the configuration, before running the command specified by ``-c`` or reading interactive input.
**-C** or **--init-command=COMMANDS**
Evaluate specified commands after reading the configuration but before executing command specified by **-c** or reading interactive input.
- ``-d`` or ``--debug=DEBUG_CATEGORIES`` enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging <debugging-fish>` below for details.
**-d** or **--debug=DEBUG_CATEGORIES**
Enables debug output and specify a pattern for matching debug categories.
See :ref:`Debugging <debugging-fish>` below for details.
- ``-o`` or ``--debug-output=DEBUG_FILE`` specify a file path to receive the debug output, including categories and :envvar:`fish_trace`. The default is stderr.
**-o** or **--debug-output=DEBUG_FILE**
Specifies a file path to receive the debug output, including categories and :envvar:`fish_trace`.
The default is stderr.
- ``-i`` or ``--interactive`` specify that fish is to run in interactive mode
**-i** or **--interactive**
The shell is interactive.
- ``-l`` or ``--login`` specify that fish is to run as a login shell
**-l** or **--login**
Act as if invoked as a login shell.
- ``-N`` or ``--no-config`` do not read configuration files
**-N** or **--no-config**
Do not read configuration files.
- ``-n`` or ``--no-execute`` do not execute any commands, only perform syntax checking
**-n** or **--no-execute**
Do not execute any commands, only perform syntax checking.
- ``-p`` or ``--profile=PROFILE_FILE`` when :command:`fish` exits, output timing information on all executed commands to the specified file. This excludes time spent starting up and reading the configuration.
**-p** or **--profile=PROFILE_FILE**
when :command:`fish` exits, output timing information on all executed commands to the specified file.
This excludes time spent starting up and reading the configuration.
- ``--profile-startup=PROFILE_FILE`` will write timing information for fish's startup to the specified file. This is useful to profile your configuration.
**--profile-startup=PROFILE_FILE**
Will write timing for ``fish`` startup to specified file.
- ``-P`` or ``--private`` enables :ref:`private mode <private-mode>`, so fish will not access old or store new history.
**-P** or **--private**
Enables :ref:`private mode <private-mode>`: **fish** will not access old or store new history.
- ``--print-rusage-self`` when :command:`fish` exits, output stats from getrusage.
**--print-rusage-self**
When :command:`fish` exits, output stats from getrusage.
- ``--print-debug-categories`` outputs the list of debug categories, and then exits.
**--print-debug-categories**
Print all debug categories, and then exit.
- ``-v`` or ``--version`` display version and exit.
**-v** or **--version**
Print version and exit.
- ``-f`` or ``--features=FEATURES`` enables one or more :ref:`feature flags <featureflags>` (separated by a comma).
These are how fish stages changes that might break scripts.
**-f** or **--features=FEATURES**
Enables one or more comma-separated :ref:`feature flags <featureflags>`.
The fish exit status is generally the :ref:`exit status of the last foreground command <variables-status>`.
The ``fish`` exit status is generally the :ref:`exit status of the last foreground command <variables-status>`.
.. _debugging-fish:
@ -62,24 +79,24 @@ Debugging
---------
While fish provides extensive support for :ref:`debugging fish scripts <debugging>`, it is also possible to debug and instrument its internals.
Debugging can be enabled by passing the ``--debug`` option.
Debugging can be enabled by passing the **--debug** option.
For example, the following command turns on debugging for background IO thread events, in addition to the default categories, i.e. *debug*, *error*, *warning*, and *warning-path*:
::
> fish --debug=iothread
Available categories are listed by ``fish --print-debug-categories``. The ``--debug`` option accepts a comma-separated list of categories, and supports glob syntax.
Available categories are listed by ``fish --print-debug-categories``. The **--debug** option accepts a comma-separated list of categories, and supports glob syntax.
The following command turns on debugging for *complete*, *history*, *history-file*, and *profile-history*, as well as the default categories:
::
> fish --debug='complete,*history*'
Debug messages output to stderr by default. Note that if ``fish_trace`` is set, execution tracing also outputs to stderr by default. You can output to a file using the ``--debug-output`` option:
Debug messages output to stderr by default. Note that if :envvar:`fish_trace` is set, execution tracing also outputs to stderr by default. You can output to a file using the **--debug-output** option:
::
> fish --debug='complete,*history*' --debug-output=/tmp/fish.log --init-command='set fish_trace on'
These options can also be changed via the :envvar:`FISH_DEBUG` and :envvar:`FISH_DEBUG_OUTPUT` variables.
The categories enabled via ``--debug`` are *added* to the ones enabled by $FISH_DEBUG, so they can be disabled by prefixing them with ``-`` (``reader-*,-ast*`` enables reader debugging and disables ast debugging).
The categories enabled via **--debug** are *added* to the ones enabled by $FISH_DEBUG, so they can be disabled by prefixing them with **-** (**reader-*,-ast*** enables reader debugging and disables ast debugging).
The file given in ``--debug-output`` takes precedence over the file in :envvar:`FISH_DEBUG_OUTPUT`.
The file given in **--debug-output** takes precedence over the file in :envvar:`FISH_DEBUG_OUTPUT`.

41
doc_src/cmds/fish_add_path.rst
View File

@ -7,9 +7,10 @@ fish_add_path - add to the path
Synopsis
--------
**fish_add_path** *path*...
.. synopsis::
**fish_add_path** [(*-g* | *--global*) | (*-U* | *--universal*) | (*-P* | *--path*)] [(*-m* | *--move*)] [(*-a* | *--append*) | (*-p* | *--prepend*)] [(*-v* | *--verbose*) | (*-n* | *--dry-run*)] *paths*...
fish_add_path path ...
fish_add_path [(-g | --global) | (-U | --universal) | (-P | --path)] [(-m | --move)] [(-a | --append) | (-p | --prepend)] [(-v | --verbose) | (-n | --dry-run)] PATHS ...
Description
@ -23,21 +24,39 @@ Components are normalized by :ref:`realpath <cmd-realpath>`. Trailing slashes ar
Components are added in the order they are given, and they are prepended to the path unless ``--append`` is given (if $fish_user_paths is used, that means they are last in $fish_user_paths, which is itself prepended to $PATH, so they still stay ahead of the system paths).
If no component is new, the variable ($fish_user_paths or $PATH) is not set again or otherwise modified, so variable handlers are not triggered.
If no component is new, the variable (:envvar:`fish_user_paths` or :envvar:`$PATH`) is not set again or otherwise modified, so variable handlers are not triggered.
If a component is not an existing directory, ``fish_add_path`` ignores it.
Options
-------
- ``-a`` or ``--append`` causes the components to be added to the *end* of the variable
- ``-p`` or ``--prepend`` causes the components to be added to the *front* of the variable (this is the default)
- ``-g`` or ``--global`` means to use a global $fish_user_paths
- ``-U`` or ``--universal`` means to use a universal $fish_user_paths - this is the default if it doesn't already exist
- ``-P`` or ``--path`` means to use $PATH directly
- ``-m`` or ``--move`` means to move already existing components to the place they would be added - by default they would be left in place and not added again
- ``-v`` or ``--verbose`` means to print the :ref:`set <cmd-set>` command used
- ``-n`` or ``--dry-run`` means to print the ``set`` command that would be used without executing it
**-a** or **--append**
Add components to the *end* of the variable.
**-p** or **--prepend**
Add components to the *front* of the variable (this is the default).
**-g** or **--global**
Use a global :envvar:`fish_user_paths`.
**-U** or **--universal**
Use a universal :envvar:`fish_user_paths` - this is the default if it doesn't already exist.
**-P** or **--path**
Manipulate :envvar:`PATH` directly.
**-m** or **--move**
Move already-existing components to the place they would be added - by default they would be left in place and not added again.
**-v** or **--verbose**
Print the :ref:`set <cmd-set>` command used.
**-n** or **--dry-run**
Print the ``set`` command that would be used without executing it.
**-h** or **--help**
Displays help about using this command.
If ``--move`` is used, it may of course lead to the path swapping order, so you should be careful doing that in config.fish.

4
doc_src/cmds/fish_breakpoint_prompt.rst
View File

@ -6,6 +6,10 @@ fish_breakpoint_prompt - define the prompt when stopped at a breakpoint
Synopsis
--------
.. synopsis::
fish_breakpoint_prompt
::
function fish_breakpoint_prompt

8
doc_src/cmds/fish_command_not_found.rst
View File

@ -6,11 +6,11 @@ fish_command_not_found - what to do when a command wasn't found
Synopsis
--------
::
.. synopsis::
function fish_command_not_found
...
end
function fish_command_not_found
...
end
Description

7
doc_src/cmds/fish_config.rst
View File

@ -6,10 +6,9 @@ fish_config - start the web-based configuration interface
Synopsis
--------
::
.. synopsis::
fish_config
fish_config browse
fish_config [browse]
fish_config prompt (choose | list | save | show)
fish_config theme (choose | demo | dump | list | save | show)
@ -44,6 +43,8 @@ Available subcommands for the ``theme`` command:
The themes are loaded from the theme directory shipped with fish or a ``themes`` directory in the fish configuration directory (typically ``~/.config/fish/themes``).
The **-h** or **--help** option displays help about using this command.
Example
-------

11
doc_src/cmds/fish_git_prompt.rst
View File

@ -6,11 +6,16 @@ fish_git_prompt - output git information for use in a prompt
Synopsis
--------
.. synopsis::
fish_git_prompt
::
function fish_prompt
printf '%s' $PWD (fish_git_prompt) ' $ '
end
function fish_prompt
printf '%s' $PWD (fish_git_prompt) ' $ '
end
Description
-----------

4
doc_src/cmds/fish_greeting.rst
View File

@ -6,6 +6,10 @@ fish_greeting - display a welcome message in interactive shells
Synopsis
--------
.. synopsis::
fish_greeting
::
function fish_greeting

6
doc_src/cmds/fish_hg_prompt.rst
View File

@ -6,6 +6,10 @@ fish_hg_prompt - output Mercurial information for use in a prompt
Synopsis
--------
.. synopsis::
fish_hg_prompt
::
function fish_prompt
@ -21,7 +25,7 @@ The fish_hg_prompt function displays information about the current Mercurial rep
By default, only the current branch is shown because ``hg status`` can be slow on a large repository. You can enable a more informative prompt by setting the variable ``$fish_prompt_hg_show_informative_status``, for example::
set --universal fish_prompt_hg_show_informative_status
set --universal fish_prompt_hg_show_informative_status
If you enabled the informative status, there are numerous customization options, which can be controlled with fish variables.

34
doc_src/cmds/fish_indent.rst
View File

@ -7,7 +7,9 @@ fish_indent - indenter and prettifier
Synopsis
--------
**fish_indent** [*OPTIONS*] [*FILE*...]
.. synopsis::
fish_indent [OPTIONS] [FILE ...]
Description
@ -17,20 +19,32 @@ Description
The following options are available:
- ``-w`` or ``--write`` indents a specified file and immediately writes to that file.
**-w** or **--write**
Indents a specified file and immediately writes to that file.
- ``-i`` or ``--no-indent`` do not indent commands; only reformat to one job per line.
**-i** or **--no-indent**
Do not indent commands; only reformat to one job per line.
- ``-c`` or ``--check`` do not indent, only return 0 if the code is already indented as fish_indent would, the number of failed files otherwise. Also print the failed filenames if not reading from stdin.
**-c** or **--check**
Do not indent, only return 0 if the code is already indented as fish_indent would, the number of failed files otherwise. Also print the failed filenames if not reading from standard input.
- ``-v`` or ``--version`` displays the current fish version and then exits.
**-v** or **--version**
Displays the current :program:`fish` version and then exits.
- ``--ansi`` colorizes the output using ANSI escape sequences, appropriate for the current $TERM, using the colors defined in the environment (such as ``$fish_color_command``).
**--ansi**
Colorizes the output using ANSI escape sequences, appropriate for the current :envvar:`TERM`, using the colors defined in the environment (such as :envvar:`fish_color_command`).
- ``--html`` outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as ``fish_color_command``.
**--html**
Outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as ``fish_color_command``.
- ``-d`` or ``--debug=DEBUG_CATEGORIES`` enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging <debugging-fish>` in :ref:`fish <cmd-fish>` (1) for details.
**-d** or **--debug=DEBUG_CATEGORIES**
Enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging <debugging-fish>` in :ref:`fish <cmd-fish>` (1) for details.
- ``-o`` or ``--debug-output=DEBUG_FILE`` specify a file path to receive the debug output, including categories and ``fish_trace``. The default is stderr.
**-o** or **--debug-output=DEBUG_FILE**
Specify a file path to receive the debug output, including categories and ``fish_trace``. The default is standard error.
- ``--dump-parse-tree`` dumps information about the parsed statements to stderr. This is likely to be of interest only to people working on the fish source code.
**--dump-parse-tree**
Dumps information about the parsed statements to standard error. This is likely to be of interest only to people working on the fish source code.
**-h** or **--help**
Displays help about using this command.

2
doc_src/cmds/fish_is_root_user.rst
View File

@ -6,7 +6,7 @@ fish_is_root_user - check if the current user is root
Synopsis
--------
::
.. synopsis::
fish_is_root_user

20
doc_src/cmds/fish_key_reader.rst
View File

@ -6,31 +6,35 @@ fish_key_reader - explore what characters keyboard keys send
Synopsis
--------
::
.. synopsis::
fish_key_reader [OPTIONS]
Description
-----------
``fish_key_reader`` is used to explain how you would bind a certain key sequence. By default, it prints the :ref:`bind <cmd-bind>` command for one key sequence read interactively over standard input.
:program:`fish_key_reader` is used to explain how you would bind a certain key sequence. By default, it prints the :ref:`bind <cmd-bind>` command for one key sequence read interactively over standard input.
If the character sequence matches a special key name (see ``bind --key-names``), both ``bind CHARS ...`` and ``bind -k KEYNAME ...`` usage will be shown. In verbose mode (enabled by passing ``--verbose``), additional details about the characters received, such as the delay between chars, are written to stderr.
If the character sequence matches a special key name (see ``bind --key-names``), both ``bind CHARS ...`` and ``bind -k KEYNAME ...`` usage will be shown. In verbose mode (enabled by passing ``--verbose``), additional details about the characters received, such as the delay between chars, are written to standard error.
The following options are available:
- ``-c`` or ``--continuous`` begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.
**-c** or **--continuous**
Begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.
- ``-V`` or ``--verbose`` tells fish_key_reader to output timing information and explain the sequence in more detail.
**-V** or **--verbose**
Tells fish_key_reader to output timing information and explain the sequence in more detail.
- ``-h`` or ``--help`` prints usage information.
**-h** or **--help**
Displays help about using this command.
- ``-v`` or ``--version`` prints fish_key_reader's version and exits.
**-v** or **--version**
Displays the current :program:`fish` version and then exits.
Usage Notes
-----------
In verbose mode, the delay in milliseconds since the previous character was received is included in the diagnostic information written to stderr. This information may be useful to determine the optimal ``fish_escape_delay_ms`` setting or learn the amount of lag introduced by tools like ``ssh``, ``mosh`` or ``tmux``.
In verbose mode, the delay in milliseconds since the previous character was received is included in the diagnostic information written to standard error. This information may be useful to determine the optimal ``fish_escape_delay_ms`` setting or learn the amount of lag introduced by tools like ``ssh``, ``mosh`` or ``tmux``.
``fish_key_reader`` intentionally disables handling of many signals. To terminate ``fish_key_reader`` in ``--continuous`` mode do:

4
doc_src/cmds/fish_mode_prompt.rst
View File

@ -6,6 +6,10 @@ fish_mode_prompt - define the appearance of the mode indicator
Synopsis
--------
.. synopsis::
fish_mode_prompt
::
function fish_mode_prompt

36
doc_src/cmds/fish_opt.rst
View File

@ -1,42 +1,48 @@
.. _cmd-fish_opt:
fish_opt - create an option spec for the argparse command
=========================================================
fish_opt - create an option specification for the argparse command
==================================================================
Synopsis
--------
::
fish_opt [ -h | --help ]
fish_opt ( -s X | --short=X ) [ -l LONG | --long=LONG ] [ --long-only ] [ -o | --optional-val ] [ -r | --required-val ] [ --multiple-vals ]
.. synopsis::
fish_opt [(-slor | --multiple-vals=) OPTNAME]
fish_opt --help
Description
-----------
This command provides a way to produce option specifications suitable for use with the :ref:`argparse <cmd-argparse>` command. You can, of course, write the option specs by hand without using this command. But you might prefer to use this for the clarity it provides.
This command provides a way to produce option specifications suitable for use with the :ref:`argparse <cmd-argparse>` command. You can, of course, write the option specifications by hand without using this command. But you might prefer to use this for the clarity it provides.
The following ``argparse`` options are available:
- ``-s`` or ``--short`` takes a single letter that is used as the short flag in the option being defined. This option is mandatory.
**-s** or **--short**
Takes a single letter that is used as the short flag in the option being defined. This option is mandatory.
- ``-l`` or ``--long`` takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option spec.
**-l** or **--long**
Takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option specification.
- ``--long-only`` means the option spec being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., ``--short`` must be specified) but it cannot be used when parsing args using this option spec.
**--long-only**
The option being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., **--short** must be specified) but it cannot be used when parsing arguments using this option specification.
- ``-o`` or ``--optional-val`` means the option being defined can take a value but it is optional rather than required. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will zero elements if no value was given with the option else it will have exactly one element.
**-o** or **--optional-val**
Tthe option being defined can take a value, but it is optional rather than required. If the option is seen more than once when parsing arguments, only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will zero elements if no value was given with the option else it will have exactly one element.
- ``-r`` or ``--required-val`` means the option being defined requires a value. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will have exactly one element.
**-r** or **--required-val**
The option being defined requires a value. If the option is seen more than once when parsing arguments, only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will have exactly one element.
- ``--multiple-vals`` means the option being defined requires a value each time it is seen. Each instance is stored. This means the resulting flag variable created by ``argparse`` will have one element for each instance of this option in the args.
**--multiple-vals**
The option being defined requires a value each time it is seen. Each instance is stored. This means the resulting flag variable created by ``argparse`` will have one element for each instance of this option in the arguments.
- ``-h`` or ``--help`` displays help about using this command.
**-h** or **--help**
Displays help about using this command.
Examples
--------
Define a single option spec for the boolean help flag:
Define a single option specification for the boolean help flag:

4
doc_src/cmds/fish_prompt.rst
View File

@ -6,6 +6,10 @@ fish_prompt - define the appearance of the command line prompt
Synopsis
--------
.. synopsis::
fish_prompt
::
function fish_prompt

8
doc_src/cmds/fish_status_to_signal.rst
View File

@ -1,11 +1,15 @@
.. _cmd-fish_status_to_signal:
fish_status_to_signal - Convert exit codes to human-friendly signals
fish_status_to_signal - convert exit codes to human-friendly signals
====================================================================
Synopsis
--------
.. synopsis::
fish_status_to_signal NUM
::
function fish_prompt
@ -26,4 +30,4 @@ Example
>_ sleep 5
^C⏎
>_ fish_status_to_signal $status
SIGINT
SIGINT

76
doc_src/cmds/fish_svn_prompt.rst
View File

@ -6,6 +6,10 @@ fish_svn_prompt - output Subversion information for use in a prompt
Synopsis
--------
.. synopsis::
fish_svn_prompt
::
function fish_prompt
@ -21,47 +25,47 @@ The fish_svn_prompt function displays information about the current Subversion r
There are numerous customization options, which can be controlled with fish variables.
- ``$__fish_svn_prompt_color_revision``
- :envvar:`__fish_svn_prompt_color_revision`
the colour of the revision number to display in the prompt
- ``$__fish_svn_prompt_char_separator``
- :envvar:`__fish_svn_prompt_char_separator`
the separator between status characters
A number of variables control the symbol ("display") and color ("color") for the different status indicators:
- ``$__fish_svn_prompt_char_added_display``
- ``$__fish_svn_prompt_char_added_color``
- ``$__fish_svn_prompt_char_conflicted_display``
- ``$__fish_svn_prompt_char_conflicted_color``
- ``$__fish_svn_prompt_char_deleted_display``
- ``$__fish_svn_prompt_char_deleted_color``
- ``$__fish_svn_prompt_char_ignored_display``
- ``$__fish_svn_prompt_char_ignored_color``
- ``$__fish_svn_prompt_char_modified_display``
- ``$__fish_svn_prompt_char_modified_color``
- ``$__fish_svn_prompt_char_replaced_display``
- ``$__fish_svn_prompt_char_replaced_color``
- ``$__fish_svn_prompt_char_unversioned_external_display``
- ``$__fish_svn_prompt_char_unversioned_external_color``
- ``$__fish_svn_prompt_char_unversioned_display``
- ``$__fish_svn_prompt_char_unversioned_color``
- ``$__fish_svn_prompt_char_missing_display``
- ``$__fish_svn_prompt_char_missing_color``
- ``$__fish_svn_prompt_char_versioned_obstructed_display``
- ``$__fish_svn_prompt_char_versioned_obstructed_color``
- ``$__fish_svn_prompt_char_locked_display``
- ``$__fish_svn_prompt_char_locked_color``
- ``$__fish_svn_prompt_char_scheduled_display``
- ``$__fish_svn_prompt_char_scheduled_color``
- ``$__fish_svn_prompt_char_switched_display``
- ``$__fish_svn_prompt_char_switched_color``
- ``$__fish_svn_prompt_char_token_present_display``
- ``$__fish_svn_prompt_char_token_present_color``
- ``$__fish_svn_prompt_char_token_other_display``
- ``$__fish_svn_prompt_char_token_other_color``
- ``$__fish_svn_prompt_char_token_stolen_display``
- ``$__fish_svn_prompt_char_token_stolen_color``
- ``$__fish_svn_prompt_char_token_broken_display``
- ``$__fish_svn_prompt_char_token_broken_color``
- :envvar:`__fish_svn_prompt_char_added_display`
- :envvar:`__fish_svn_prompt_char_added_color`
- :envvar:`__fish_svn_prompt_char_conflicted_display`
- :envvar:`__fish_svn_prompt_char_conflicted_color`
- :envvar:`__fish_svn_prompt_char_deleted_display`
- :envvar:`__fish_svn_prompt_char_deleted_color`
- :envvar:`__fish_svn_prompt_char_ignored_display`
- :envvar:`__fish_svn_prompt_char_ignored_color`
- :envvar:`__fish_svn_prompt_char_modified_display`
- :envvar:`__fish_svn_prompt_char_modified_color`
- :envvar:`__fish_svn_prompt_char_replaced_display`
- :envvar:`__fish_svn_prompt_char_replaced_color`
- :envvar:`__fish_svn_prompt_char_unversioned_external_display`
- :envvar:`__fish_svn_prompt_char_unversioned_external_color`
- :envvar:`__fish_svn_prompt_char_unversioned_display`
- :envvar:`__fish_svn_prompt_char_unversioned_color`
- :envvar:`__fish_svn_prompt_char_missing_display`
- :envvar:`__fish_svn_prompt_char_missing_color`
- :envvar:`__fish_svn_prompt_char_versioned_obstructed_display`
- :envvar:`__fish_svn_prompt_char_versioned_obstructed_color`
- :envvar:`__fish_svn_prompt_char_locked_display`
- :envvar:`__fish_svn_prompt_char_locked_color`
- :envvar:`__fish_svn_prompt_char_scheduled_display`
- :envvar:`__fish_svn_prompt_char_scheduled_color`
- :envvar:`__fish_svn_prompt_char_switched_display`
- :envvar:`__fish_svn_prompt_char_switched_color`
- :envvar:`__fish_svn_prompt_char_token_present_display`
- :envvar:`__fish_svn_prompt_char_token_present_color`
- :envvar:`__fish_svn_prompt_char_token_other_display`
- :envvar:`__fish_svn_prompt_char_token_other_color`
- :envvar:`__fish_svn_prompt_char_token_stolen_display`
- :envvar:`__fish_svn_prompt_char_token_stolen_color`
- :envvar:`__fish_svn_prompt_char_token_broken_display`
- :envvar:`__fish_svn_prompt_char_token_broken_color`
See also :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>`, which will call all supported version control prompt functions, including git, Mercurial and Subversion.

4
doc_src/cmds/fish_title.rst
View File

@ -6,6 +6,10 @@ fish_title - define the terminal's title
Synopsis
--------
.. synopsis::
fish_title
::
function fish_title

4
doc_src/cmds/fish_update_completions.rst
View File

@ -6,9 +6,9 @@ fish_update_completions - update completions using manual pages
Synopsis
--------
::
.. synopsis::
fish_update_completions
fish_update_completions
Description
-----------

6
doc_src/cmds/fish_vcs_prompt.rst
View File

@ -6,6 +6,10 @@ fish_vcs_prompt - output version control system information for use in a prompt
Synopsis
--------
.. synopsis::
fish_vcs_prompt
::
function fish_prompt
@ -25,7 +29,7 @@ It calls out to VCS-specific functions. The currently supported systems are:
If a VCS isn't installed, the respective function does nothing.
The svn prompt is disabled by default because it's slow on large svn repositories. To enable it, modify fish_vcs_prompt to uncomment it. See :ref:`funced <cmd-funced>`.
The Subversion prompt is disabled by default, because it's slow on large repositories. To enable it, modify ``fish_vcs_prompt`` to uncomment it. See :ref:`funced <cmd-funced>`.
For more information, see the documentation for each of the functions above.

14
doc_src/cmds/for.rst
View File

@ -6,22 +6,22 @@ for - perform a set of commands multiple times
Synopsis
--------
::
.. synopsis::
for VARNAME in [VALUES...]; COMMANDS...; end
for VARNAME in [VALUES ...]; COMMANDS ...; end
Description
-----------
``for`` is a loop construct. It will perform the commands specified by ``COMMANDS`` multiple times. On each iteration, the local variable specified by ``VARNAME`` is assigned a new value from ``VALUES``. If ``VALUES`` is empty, ``COMMANDS`` will not be executed at all. The ``VARNAME`` is visible when the loop terminates and will contain the last value assigned to it. If ``VARNAME`` does not already exist it will be set in the local scope. For our purposes if the ``for`` block is inside a function there must be a local variable with the same name. If the ``for`` block is not nested inside a function then global and universal variables of the same name will be used if they exist.
**for** is a loop construct. It will perform the commands specified by *COMMANDS* multiple times. On each iteration, the local variable specified by *VARNAME* is assigned a new value from *VALUES*. If *VALUES* is empty, *COMMANDS* will not be executed at all. The *VARNAME* is visible when the loop terminates and will contain the last value assigned to it. If *VARNAME* does not already exist it will be set in the local scope. For our purposes if the **for** block is inside a function there must be a local variable with the same name. If the **for** block is not nested inside a function then global and universal variables of the same name will be used if they exist.
Much like :ref:`set <cmd-set>`, ``for`` does not modify $status, but the evaluation of its subordinate commands can.
Much like :ref:`set <cmd-set>`, **for** does not modify $status, but the evaluation of its subordinate commands can.
The **-h** or **--help** option displays help about using this command.
Example
-------
::
for i in foo bar baz; echo $i; end
@ -37,8 +37,6 @@ Notes
The ``VARNAME`` was local to the for block in releases prior to 3.0.0. This means that if you did something like this:
::
for var in a b c

18
doc_src/cmds/funced.rst
View File

@ -6,26 +6,32 @@ funced - edit a function interactively
Synopsis
--------
::
.. synopsis::
funced [OPTIONS] NAME
Description
-----------
``funced`` provides an interface to edit the definition of the function ``NAME``.
``funced`` provides an interface to edit the definition of the function *NAME*.
If the ``$VISUAL`` environment variable is set, it will be used as the program to edit the function. If ``$VISUAL`` is unset but ``$EDITOR`` is set, that will be used. Otherwise, a built-in editor will be used. Note that to enter a literal newline using the built-in editor you should press :kbd:`Alt`\ +\ :kbd:`Enter`. Pressing :kbd:`Enter` signals that you are done editing the function. This does not apply to an external editor like emacs or vim.
``funced`` will try to edit the original file that a function is defined in, which might include variable definitions or helper functions as well. If changes cannot be saved to the original file, a copy will be created in the user's function directory.
If there is no function called ``NAME``, a new function will be created with the specified name.
If there is no function called *NAME*, a new function will be created with the specified name.
- ``-e command`` or ``--editor command`` Open the function body inside the text editor given by the command (for example, ``-e vi``). The special command ``fish`` will use the built-in editor (same as specifying ``-i``).
**-e command** or **--editor command**
Open the function body inside the text editor given by the command (for example, **-e vi**). The special command ``fish`` will use the built-in editor (same as specifying **-i**).
- ``-i`` or ``--interactive`` Force opening the function body in the built-in editor even if ``$VISUAL`` or ``$EDITOR`` is defined.
**-i** or **--interactive**
Force opening the function body in the built-in editor even if ``$VISUAL`` or ``$EDITOR`` is defined.
- ``-s`` or ``--save`` Automatically save the function after successfully editing it.
**-s** or **--save**
Automatically save the function after successfully editing it.
**-h** or **--help**
Displays help about using this command.
Example
-------

6
doc_src/cmds/funcsave.rst
View File

@ -6,10 +6,10 @@ funcsave - save the definition of a function to the user's autoload directory
Synopsis
--------
::
.. synopsis::
funcsave FUNCTION_NAME
funcsave [-q] [(-d | --directory) DIR ] FUNCTION_NAME
funcsave [-q] [(-d | --directory) DIR] FUNCTION_NAME
Description
@ -17,6 +17,8 @@ Description
``funcsave`` saves a function to a file in the fish configuration directory. This function will be :ref:`automatically loaded <syntax-function-autoloading>` by current and future fish sessions. This can be useful to commit functions created interactively for permanent use.
If you have erased a function using :ref:`functions <cmd-functions>`'s ``--erase`` option, ``funcsave`` will remove the saved function definition.
Because fish loads functions on-demand, saved functions cannot serve as :ref:`event handlers <event>` until they are run or otherwise sourced. To activate an event handler for every new shell, add the function to the :ref:`configuration file <configuration>` instead of using ``funcsave``.
This is often used after :ref:`funced <cmd-funced>`, which opens the function in ``$EDITOR`` or ``$VISUAL`` and loads it into the current session afterwards.

40
doc_src/cmds/function.rst
View File

@ -6,7 +6,7 @@ function - create a function
Synopsis
--------
::
.. synopsis::
function NAME [OPTIONS]; BODY; end
@ -14,35 +14,43 @@ Synopsis
Description
-----------
``function`` creates a new function ``NAME`` with the body ``BODY``.
``function`` creates a new function *NAME* with the body *BODY*.
A function is a list of commands that will be executed when the name of the function is given as a command.
The following options are available:
- ``-a NAMES`` or ``--argument-names NAMES`` assigns the value of successive command-line arguments to the names given in NAMES.
**-a** *NAMES* or **--argument-names** *NAMES*
Assigns the value of successive command-line arguments to the names given in *NAMES*.
- ``-d DESCRIPTION`` or ``--description=DESCRIPTION`` is a description of what the function does, suitable as a completion description.
**-d** *DESCRIPTION* or **--description** *DESCRIPTION*
A description of what the function does, suitable as a completion description.
- ``-w WRAPPED_COMMAND`` or ``--wraps=WRAPPED_COMMAND`` causes the function to inherit completions from the given wrapped command. See the documentation for :ref:`complete <cmd-complete>` for more information.
**-w** *WRAPPED_COMMAND* or **--wraps** *WRAPPED_COMMAND*
Inherit completions from the given *WRAPPED_COMMAND*. See the documentation for :ref:`complete <cmd-complete>` for more information.
- ``-e`` or ``--on-event EVENT_NAME`` tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
**-e** *EVENT_NAME* or **--on-event** *EVENT_NAME*
Run this function when the specified named event is emitted. Fish internally generates named events, for example,when showing the prompt. Custom events can be emitted using the :ref:`emit <cmd-emit>` command.
- ``-v`` or ``--on-variable VARIABLE_NAME`` tells fish to run this function when the variable VARIABLE_NAME changes value. Note that fish makes no guarantees on any particular timing or even that the function will be run for every single ``set``. Rather it will be run when the variable has been set at least once, possibly skipping some values or being run when the variable has been set to the same value (except for universal variables set in other shells - only changes in the value will be picked up for those).
**-v** *VARIABLE_NAME* or **--on-variable** *VARIABLE_NAME*
Run this function when the variable *VARIABLE_NAME* changes value. Note that :program:`fish`` makes no guarantees on any particular timing or even that the function will be run for every single ``set``. Rather it will be run when the variable has been set at least once, possibly skipping some values or being run when the variable has been set to the same value (except for universal variables set in other shells - only changes in the value will be picked up for those).
- ``-j PID`` or ``--on-job-exit PID`` tells fish to run this function when the job containing a child process with the given PID exits. Instead of PID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
**-j** *PID* or **--on-job-exit** *PID*
Run this function when the job containing a child process with the given process identifier *PID* exits. Instead of a PID, the string 'caller' can be specified. This is only allowed when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
- ``-p PID`` or ``--on-process-exit PID`` tells fish to run this function when the fish child process
with process ID PID exits. Instead of a PID, for backward compatibility,
"``%self``" can be specified as an alias for ``$fish_pid``, and the function will be run when the
current fish instance exits.
**-p** *PID* or **--on-process-exit** *PID*
Run this function when the fish child process with process ID PID exits. Instead of a PID, for backward compatibility, "``%self``" can be specified as an alias for ``$fish_pid``, and the function will be run when the current fish instance exits.
- ``-s`` or ``--on-signal SIGSPEC`` tells fish to run this function when the signal ``SIGSPEC`` is delivered. ``SIGSPEC`` can be a signal number, or the signal name, such as ``SIGHUP`` (or just ``HUP``). Note that the signal must have been delivered to fish; for example, :kbd:`Ctrl-C` sends ``SIGINT`` to the foreground process group, which will not be fish if you are running another command at the time.
**-s** *SIGSPEC* or **--on-signal** *SIGSPEC*
Run this function when the signal ``SIGSPEC`` is delivered. ``SIGSPEC`` can be a signal number, or the signal name, such as ``SIGHUP`` (or just ``HUP``). Note that the signal must have been delivered to :program:`fish`; for example, :kbd:`Ctrl-C` sends ``SIGINT`` to the foreground process group, which will not be :program:`fish` if you are running another command at the time.
- ``-S`` or ``--no-scope-shadowing`` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents are independent of the calling function.
It's important to note that this does not capture referenced variables or the scope at the time of function declaration! At this time, fish does not have any concept of closures, and variable lifetimes are never extended. In other words, by using ``--no-scope-shadowing`` the scope of the function each time it is run is shared with the scope it was *called* from rather than the scope it was *defined* in.
**-S** or **--no-scope-shadowing**
Allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents are independent of the calling function.
- ``-V`` or ``--inherit-variable NAME`` snapshots the value of the variable ``NAME`` and defines a local variable with that same name and value when the function is defined. This is similar to a closure in other languages like Python but a bit different. Note the word "snapshot" in the first sentence. If you change the value of the variable after defining the function, even if you do so in the same scope (typically another function) the new value will not be used by the function you just created using this option. See the ``function notify`` example below for how this might be used.
It's important to note that this does not capture referenced variables or the scope at the time of function declaration! At this time, fish does not have any concept of closures, and variable lifetimes are never extended. In other words, by using **--no-scope-shadowing** the scope of the function each time it is run is shared with the scope it was *called* from rather than the scope it was *defined* in.
**-V** or **--inherit-variable NAME**
Snapshots the value of the variable ``NAME`` and defines a local variable with that same name and value when the function is defined. This is similar to a closure in other languages like Python but a bit different. Note the word "snapshot" in the first sentence. If you change the value of the variable after defining the function, even if you do so in the same scope (typically another function) the new value will not be used by the function you just created using this option. See the ``function notify`` example below for how this might be used.
If the user enters any additional arguments after the function, they are inserted into the environment :ref:`variable list <variables-lists>` ``$argv``. If the ``--argument-names`` option is provided, the arguments are also assigned to names specified in that option.

50
doc_src/cmds/functions.rst
View File

@ -6,13 +6,13 @@ functions - print or erase functions
Synopsis
--------
::
.. synopsis::
functions [ -a | --all ] [ -n | --names ]
functions [ -D | --details ] [ -v ] FUNCTION
functions [-a | --all] [-n | --names]
functions [-D | --details] [-v] FUNCTION
functions -c OLDNAME NEWNAME
functions -d DESCRIPTION FUNCTION
functions [ -e | -q ] FUNCTIONS...
functions [-e | -q] FUNCTION ...
Description
-----------
@ -21,35 +21,49 @@ Description
The following options are available:
- ``-a`` or ``--all`` lists all functions, even those whose name starts with an underscore.
**-a** or **--all**
Lists all functions, even those whose name starts with an underscore.
- ``-c OLDNAME NEWNAME`` or ``--copy OLDNAME NEWNAME`` creates a new function named NEWNAME, using the definition of the OLDNAME function.
**-c** or **--copy** *OLDNAME* *NEWNAME*
Creates a new function named *NEWNAME*, using the definition of the *OLDNAME* function.
- ``-d DESCRIPTION`` or ``--description=DESCRIPTION`` changes the description of this function.
**-d** or **--description** *DESCRIPTION*
Changes the description of this function.
- ``-e`` or ``--erase`` causes the specified functions to be erased. This also means that it is prevented from autoloading.
**-e** or **--erase**
Causes the specified functions to be erased. This also means that it is prevented from autoloading in the current session. Use :ref:`funcsave <cmd-funcsave>` to remove the saved copy.
- ``-D`` or ``--details`` reports the path name where the specified function is defined or could be autoloaded, ``stdin`` if the function was defined interactively or on the command line or by reading stdin, ``-`` if the function was created via :ref:`source <cmd-source>`, and ``n/a`` if the function isn't available. (Functions created via :ref:`alias <cmd-alias>` will return ``-``, because ``alias`` uses ``source`` internally.) If the ``--verbose`` option is also specified then five lines are written:
**-D** or **--details**
Reports the path name where the specified function is defined or could be autoloaded, ``stdin`` if the function was defined interactively or on the command line or by reading standard input, **-** if the function was created via :ref:`source <cmd-source>`, and ``n/a`` if the function isn't available. (Functions created via :ref:`alias <cmd-alias>` will return **-**, because ``alias`` uses ``source`` internally.) If the **--verbose** option is also specified then five lines are written:
- the pathname as already described,
- ``autoloaded``, ``not-autoloaded`` or ``n/a``,
- the line number within the file or zero if not applicable,
- ``scope-shadowing`` if the function shadows the vars in the calling function (the normal case if it wasn't defined with ``--no-scope-shadowing``), else ``no-scope-shadowing``, or ``n/a`` if the function isn't defined,
- the function description minimally escaped so it is a single line or ``n/a`` if the function isn't defined.
- ``scope-shadowing`` if the function shadows the vars in the calling function (the normal case if it wasn't defined with **--no-scope-shadowing**), else ``no-scope-shadowing``, or ``n/a`` if the function isn't defined,
- the function description minimally escaped so it is a single line, or ``n/a`` if the function isn't defined or has no description.
You should not assume that only five lines will be written since we may add additional information to the output in the future.
You should not assume that only five lines will be written since we may add additional information to the output in the future.
- ``--no-details`` turns off function path reporting, so just the definition will be printed.
**--no-details**
Turns off function path reporting, so just the definition will be printed.
- ``-n`` or ``--names`` lists the names of all defined functions.
**-n** or **--names**
Lists the names of all defined functions.
- ``-q`` or ``--query`` tests if the specified functions exist.
**-q** or **--query**
Tests if the specified functions exist.
- ``-v`` or ``--verbose`` will make some output more verbose.
**-v** or **--verbose**
Make some output more verbose.
- ``-H`` or ``--handlers`` will show all event handlers.
**-H** or **--handlers**
Show all event handlers.
- ``-t`` or ``--handlers-type TYPE`` will show all event handlers matching the given type
**-t** or **--handlers-type** *TYPE*
Show all event handlers matching the given *TYPE*.
**-h** or **--help**
Displays help about using this command.
The default behavior of ``functions``, when called with no arguments, is to print the names of all defined functions. Unless the ``-a`` option is given, no functions starting with underscores are included in the output.

19
doc_src/cmds/help.rst
View File

@ -6,7 +6,7 @@ help - display fish documentation
Synopsis
--------
::
.. synopsis::
help [SECTION]
@ -15,16 +15,21 @@ Description
``help`` displays the fish help documentation.
If a ``SECTION`` is specified, the help for that command is shown.
If a *SECTION* is specified, the help for that command is shown.
If the BROWSER environment variable is set, it will be used to display the documentation. Otherwise, fish will search for a suitable browser.
If you prefer to use a different browser (other than as described above) for fish help, you can set the fish_help_browser variable. This variable may be set as a list, where the first element is the browser command and the rest are browser options.
Note that most builtin commands display their help in the terminal when given the ``--help`` option.
The **-h** or **--help** option displays help about using this command.
If the :envvar:`BROWSER`` environment variable is set, it will be used to display the documentation.
Otherwise, fish will search for a suitable browser.
To use a different browser than as described above, one can set the :envvar:`fish_help_browser` variable.
This variable may be set as a list, where the first element is the browser command and the rest are browser options.
Example
-------
``help fg`` shows the documentation for the :ref:`fg <cmd-fg>` builtin.
Notes
-----
Most builtin commands, including this one, display their help in the terminal when given the **--help** option.

57
doc_src/cmds/history.rst
View File

@ -6,15 +6,17 @@ history - show and manipulate command history
Synopsis
--------
::
.. synopsis::
history [ search ] [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] [ --max=n ] [ --null ] [ -R | --reverse ] [ "search string"... ]
history delete [ --show-time ] [ --case-sensitive ] [ --exact | --prefix | --contains ] "search string"...
history [search] [--show-time] [--case-sensitive]
[--exact | --prefix | --contains] [--max N] [--null] [--reverse]
[SEARCH_STRING ...]
history delete [--case-sensitive]
[--exact | --prefix | --contains] SEARCH_STRING ...
history merge
history save
history clear
history clear-session
history ( -h | --help )
Description
-----------
@ -23,39 +25,54 @@ Description
The following operations (sub-commands) are available:
- ``search`` returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to explicitly say ``history search`` if you wish to search for one of the subcommands. The ``--contains`` search option will be used if you don't specify a different search option. Entries are ordered newest to oldest unless you use the ``--reverse`` flag. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin simply writes the results to stdout.
**search**
Returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to explicitly say ``history search`` if you wish to search for one of the subcommands. The ``--contains`` search option will be used if you don't specify a different search option. Entries are ordered newest to oldest unless you use the ``--reverse`` flag. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin simply writes the results to stdout.
- ``delete`` deletes history items. The ``--contains`` search option will be used if you don't specify a different search option. If you don't specify ``--exact`` a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID separated by a space to delete multiple entries. Just press [enter] to not delete anything. Note that the interactive delete behavior is a feature of the history function. The history builtin only supports ``--exact --case-sensitive`` deletion.
**delete**
Deletes history items. The ``--contains`` search option will be used if you don't specify a different search option. If you don't specify ``--exact`` a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID separated by a space to delete multiple entries. Just press [enter] to not delete anything. Note that the interactive delete behavior is a feature of the history function. The history builtin only supports ``--exact --case-sensitive`` deletion.
- ``merge`` immediately incorporates history changes from other sessions. Ordinarily ``fish`` ignores history changes from sessions started after the current one. This command applies those changes immediately.
**merge**
Immediately incorporates history changes from other sessions. Ordinarily ``fish`` ignores history changes from sessions started after the current one. This command applies those changes immediately.
- ``save`` immediately writes all changes to the history file. The shell automatically saves the history file; this option is provided for internal use and should not normally need to be used by the user.
**save**
Immediately writes all changes to the history file. The shell automatically saves the history file; this option is provided for internal use and should not normally need to be used by the user.
- ``clear`` clears the history file. A prompt is displayed before the history is erased asking you to confirm you really want to clear all history unless ``builtin history`` is used.
**clear**
Clears the history file. A prompt is displayed before the history is erased asking you to confirm you really want to clear all history unless ``builtin history`` is used.
- ``clear-session`` clears the history file from all activity of the current session. Note: If ``history merge`` or ``builtin history merge`` is run in a session only the history after this will be erased.
**clear-session**
Clears the history file from all activity of the current session. Note: If ``history merge`` or ``builtin history merge`` is run in a session, only the history after this will be erased.
The following options are available:
These flags can appear before or immediately after one of the sub-commands listed above.
- ``-C`` or ``--case-sensitive`` does a case-sensitive search. The default is case-insensitive. Note that prior to fish 2.4.0 the default was case-sensitive.
**-C** or **--case-sensitive**
Does a case-sensitive search. The default is case-insensitive. Note that prior to fish 2.4.0 the default was case-sensitive.
- ``-c`` or ``--contains`` searches or deletes items in the history that contain the specified text string. This is the default for the ``--search`` flag. This is not currently supported by the ``delete`` subcommand.
**-c** or **--contains**
Searches items in the history that contain the specified text string. This is the default for the **--search** flag. This is not currently supported by the **delete** subcommand.
- ``-e`` or ``--exact`` searches or deletes items in the history that exactly match the specified text string. This is the default for the ``delete`` subcommand. Note that the match is case-insensitive by default. If you really want an exact match, including letter case, you must use the ``-C`` or ``--case-sensitive`` flag.
**-e** or **--exact**
Searches or deletes items in the history that exactly match the specified text string. This is the default for the **delete** subcommand. Note that the match is case-insensitive by default. If you really want an exact match, including letter case, you must use the **-C** or **--case-sensitive** flag.
- ``-p`` or ``--prefix`` searches or deletes items in the history that begin with the specified text string. This is not currently supported by the ``--delete`` flag.
**-p** or **--prefix**
Searches items in the history that begin with the specified text string. This is not currently supported by the **delete** subcommand.
- ``-t`` or ``--show-time`` prepends each history entry with the date and time the entry was recorded. By default it uses the strftime format ``# %c%n``. You can specify another format; e.g., ``--show-time="%Y-%m-%d %H:%M:%S "`` or ``--show-time="%a%I%p"``. The short option, ``-t``, doesn't accept a strftime format string; it only uses the default format. Any strftime format is allowed, including ``%s`` to get the raw UNIX seconds since the epoch.
**-t** or **--show-time**
Prepends each history entry with the date and time the entry was recorded. By default it uses the strftime format ``# %c%n``. You can specify another format; e.g., ``--show-time="%Y-%m-%d %H:%M:%S "`` or ``--show-time="%a%I%p"``. The short option, **-t**, doesn't accept a strftime format string; it only uses the default format. Any strftime format is allowed, including ``%s`` to get the raw UNIX seconds since the epoch.
- ``-z`` or ``--null`` causes history entries written by the search operations to be terminated by a NUL character rather than a newline. This allows the output to be processed by ``read -z`` to correctly handle multiline history entries.
**-z** or **--null**
Causes history entries written by the search operations to be terminated by a NUL character rather than a newline. This allows the output to be processed by ``read -z`` to correctly handle multiline history entries.
- ``-<number>`` ``-n <number>`` or ``--max=<number>`` limits the matched history items to the first "n" matching entries. This is only valid for ``history search``.
**-**\*NUMBER* **-n** *NUMBER* or **--max** *NUMBER*
Limits the matched history items to the first *NUMBER* matching entries. This is only valid for ``history search``.
- ``-R`` or ``--reverse`` causes the history search results to be ordered oldest to newest. Which is the order used by most shells. The default is newest to oldest.
**-R** or **--reverse**
Causes the history search results to be ordered oldest to newest. Which is the order used by most shells. The default is newest to oldest.
- ``-h`` or ``--help`` display help for this command.
**-h** or **--help**
Displays help for this command.
Example
-------
@ -89,6 +106,6 @@ Other shells such as bash and zsh use a variable named ``HISTFILE`` for a simila
Notes
-----
If you specify both ``--prefix`` and ``--contains`` the last flag seen is used.
If you specify both **--prefix** and **--contains** the last flag seen is used.
Note that for backwards compatibility each subcommand can also be specified as a long option. For example, rather than ``history search`` you can type ``history --search``. Those long options are deprecated and will be removed in a future release.

10
doc_src/cmds/if.rst
View File

@ -6,11 +6,11 @@ if - conditionally execute a command
Synopsis
--------
::
.. synopsis::
if CONDITION; COMMANDS_TRUE...;
[else if CONDITION2; COMMANDS_TRUE2...;]
[else; COMMANDS_FALSE...;]
if CONDITION; COMMANDS_TRUE ...;
[else if CONDITION2; COMMANDS_TRUE2 ...;]
[else; COMMANDS_FALSE ...;]
end
Description
@ -22,6 +22,8 @@ You can use :ref:`and <cmd-and>` or :ref:`or <cmd-or>` in the condition. See the
The exit status of the last foreground command to exit can always be accessed using the :ref:`$status <variables-status>` variable.
The **-h** or **--help** option displays help about using this command.
Example
-------

15
doc_src/cmds/isatty.rst
View File

@ -6,7 +6,7 @@ isatty - test if a file descriptor is a terminal
Synopsis
--------
::
.. synopsis::
isatty [FILE DESCRIPTOR]
@ -19,15 +19,12 @@ Description
If the specified file descriptor is a terminal device, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error.
The **-h** or **--help** option displays help about using this command.
Examples
--------
From an interactive shell, the commands below exit with a return value of zero:
::
From an interactive shell, the commands below exit with a return value of zero::
isatty
isatty stdout
@ -35,11 +32,7 @@ From an interactive shell, the commands below exit with a return value of zero:
echo | isatty 1
And these will exit non-zero:
::
And these will exit non-zero::
echo | isatty
isatty 9

26
doc_src/cmds/jobs.rst
View File

@ -6,9 +6,9 @@ jobs - print currently running jobs
Synopsis
--------
::
.. synopsis::
jobs [OPTIONS] [ PID | %JOBID ]
jobs [OPTIONS] [PID | %JOBID]
Description
@ -16,21 +16,29 @@ Description
``jobs`` prints a list of the currently running :ref:`jobs <syntax-job-control>` and their status.
jobs accepts the following switches:
``jobs`` accepts the following options:
- ``-c`` or ``--command`` prints the command name for each process in jobs.
**-c** or **--command**
Prints the command name for each process in jobs.
- ``-g`` or ``--group`` only prints the group ID of each job.
**-g** or **--group**
Only prints the group ID of each job.
- ``-l`` or ``--last`` prints only the last job to be started.
**-l** or **--last**
Prints only the last job to be started.
- ``-p`` or ``--pid`` prints the process ID for each process in all jobs.
**-p** or **--pid**
Prints the process ID for each process in all jobs.
- ``-q`` or ``--query`` prints no output for evaluation of jobs by exit status only. For compatibility with old fish versions this is also ``--quiet`` (but this is deprecated).
**-q** or **--query**
Prints no output for evaluation of jobs by exit status only. For compatibility with old fish versions this is also **--quiet** (but this is deprecated).
**-h** or **--help**
Displays help about using this command.
On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%.
Arguments of the form ``PID`` or ``%JOBID`` restrict the output to jobs with the selected process identifiers or job numbers respectively.
Arguments of the form *PID* or *%JOBID* restrict the output to jobs with the selected process identifiers or job numbers respectively.
If the output of ``jobs`` is redirected or if it is part of a command substitution, the column header that is usually printed is omitted, making it easier to parse.

157
doc_src/cmds/math.rst
View File

@ -6,30 +6,50 @@ math - perform mathematics calculations
Synopsis
--------
::
.. synopsis::
math [-sN | --scale=N] [-bBASE | --base=BASE] [--] EXPRESSION
math [(-s | --scale) N] [(-b | --base) BASE] EXPRESSION ...
Description
-----------
``math`` performs mathematical calculations. It supports simple operations such as addition, subtraction, and so on, as well as functions like ``abs()``, ``sqrt()`` and ``ln()``.
``math`` performs mathematical calculations.
It supports simple operations such as addition, subtraction, and so on, as well as functions like ``abs()``, ``sqrt()`` and ``ln()``.
By default, the output is a floating-point number with trailing zeroes trimmed. To get a fixed representation, the ``--scale`` option can be used, including ``--scale=0`` for integer output.
By default, the output is a floating-point number with trailing zeroes trimmed.
To get a fixed representation, the ``--scale`` option can be used, including ``--scale=0`` for integer output.
Keep in mind that parameter expansion happens before expressions are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis (``()``) and the asterisk (``*``) glob character have to be escaped or quoted. ``x`` can also be used to denote multiplication, but it needs to be followed by whitespace to distinguish it from hexadecimal numbers.
Keep in mind that parameter expansion happens before expressions are evaluated.
This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis (``()``) and the asterisk (``*``) glob character have to be escaped or quoted.
``x`` can also be used to denote multiplication, but it needs to be followed by whitespace to distinguish it from hexadecimal numbers.
Parentheses for functions are optional - ``math sin pi`` prints ``0``. However, a comma will bind to the inner function, so ``math pow sin 3, 5`` is an error because it tries to give ``sin`` the arguments ``3`` and ``5``. When in doubt, use parentheses.
``math`` ignores whitespace between arguments and takes its input as multiple arguments (internally joined with a space), so ``math 2 +2`` and ``math "2 + 2"`` work the same. ``math 2 2`` is an error.
Parentheses for functions are optional - ``math sin pi`` prints ``0``.
However, a comma will bind to the inner function, so ``math pow sin 3, 5`` is an error because it tries to give ``sin`` the arguments ``3`` and ``5``.
When in doubt, use parentheses.
``math`` ignores whitespace between arguments and takes its input as multiple arguments (internally joined with a space), so ``math 2 +2`` and ``math "2 + 2"`` work the same.
``math 2 2`` is an error.
The following options are available:
- ``-sN`` or ``--scale=N`` sets the scale of the result. ``N`` must be an integer or the word "max" for the maximum scale. A scale of zero causes results to be rounded down to the nearest integer. So ``3/2`` returns ``1`` rather than ``2`` which ``1.5`` would normally round to. This is for compatibility with ``bc`` which was the basis for this command prior to fish 3.0.0. Scale values greater than zero causes the result to be rounded using the usual rules to the specified number of decimal places.
**-s** *N* or **--scale** *N*
Sets the scale of the result.
``N`` must be an integer or the word "max" for the maximum scale.
A scale of zero causes results to be rounded down to the nearest integer.
So ``3/2`` returns ``1`` rather than ``2`` which ``1.5`` would normally round to.
This is for compatibility with ``bc`` which was the basis for this command prior to fish 3.0.0.
Scale values greater than zero causes the result to be rounded using the usual rules to the specified number of decimal places.
- ``-b BASE`` or ``--base BASE`` sets the numeric base used for output (``math`` always understands hexadecimal numbers as input). It currently understands "hex" or "16" for hexadecimal and "octal" or "8" for octal and implies a scale of 0 (other scales cause an error), so it will truncate the result down to an integer. This might change in the future. Hex numbers will be printed with a ``0x`` prefix. Octal numbers will have a prefix of ``0`` and aren't understood by ``math`` as input.
**-b** *BASE* or **--base** *BASE*
Sets the numeric base used for output (``math`` always understands hexadecimal numbers as input).
It currently understands "hex" or "16" for hexadecimal and "octal" or "8" for octal and implies a scale of 0 (other scales cause an error), so it will truncate the result down to an integer.
This might change in the future.
Hex numbers will be printed with a ``0x`` prefix.
Octal numbers will have a prefix of ``0`` but aren't understood by ``math`` as input.
**-h** or **--help**
Displays help about using this command.
Return Values
-------------
@ -41,22 +61,30 @@ Syntax
``math`` knows some operators, constants, functions and can (obviously) read numbers.
For numbers, ``.`` is always the radix character regardless of locale - ``2.5``, not ``2,5``. Scientific notation (``10e5``) and hexadecimal (``0xFF``) are also available.
For numbers, ``.`` is always the radix character regardless of locale - ``2.5``, not ``2,5``.
Scientific notation (``10e5``) and hexadecimal (``0xFF``) are also available.
Operators
---------
``math`` knows the following operators:
- ``+`` for addition and ``-`` for subtraction.
- ``*`` or ``x`` for multiplication, ``/`` for division. (Note that ``*`` is the glob character and needs to be quoted or escaped, ``x`` needs to be followed by whitespace or it looks like ``0x`` hexadecimal notation.)
- ``^`` for exponentiation.
- ``%`` for modulo.
- ``(`` and ``)`` for grouping. (These need to be quoted or escaped because ``()`` denotes a command substitution.)
``+``
for addition
``-``
for subtraction
``*`` or ``x``
for multiplication
``/``
for division
(Note that ``*`` is the glob character and needs to be quoted or escaped, ``x`` needs to be followed by whitespace or it looks like ``0x`` hexadecimal notation.)
``^``
for exponentiation
``%``
for modulo
``(`` or ``)``
for grouping.
(These need to be quoted or escaped because ``()`` denotes a command substitution.)
They are all used in an infix manner - ``5 + 2``, not ``+ 5 2``.
@ -65,9 +93,13 @@ Constants
``math`` knows the following constants:
- ``e`` - Euler's number.
- ``pi`` - π. You know this one. Half of Tau.
- ``tau``. Equivalent to 2π, or the number of radians in a circle.
``e``
Euler's number
``pi``
π, you know this one.
Half of Tau
``tau``
Equivalent to 2π, or the number of radians in a circle
Use them without a leading ``$`` - ``pi - 3`` should be about 0.
@ -76,32 +108,59 @@ Functions
``math`` supports the following functions:
- ``abs`` - the absolute value, with positive sign
- ``acos`` - arc cosine
- ``asin`` - arc sine
- ``atan`` - arc tangent
- ``atan2`` - arc tangent of two variables
- ``bitand``, ``bitor`` and ``bitxor`` to perform bitwise operations. These will throw away any non-integer parts and interpret the rest as an int.
- ``ceil`` - round number up to nearest integer
- ``cos`` - the cosine
- ``cosh`` - hyperbolic cosine
- ``exp`` - the base-e exponential function
- ``fac`` - factorial - also known as ``x!`` (``x * (x - 1) * (x - 2) * ... * 1``)
- ``floor`` - round number down to nearest integer
- ``ln`` - the base-e logarithm
- ``log`` or ``log10`` - the base-10 logarithm
- ``log2`` - the base-2 logarithm
- ``max`` - returns the larger of two numbers
- ``min`` - returns the smaller of two numbers
- ``ncr`` - "from n choose r" combination function - how many subsets of size r can be taken from n (order doesn't matter)
- ``npr`` - the number of subsets of size r that can be taken from a set of n elements (including different order)
- ``pow(x,y)`` returns x to the y (and can be written as ``x ^ y``)
- ``round`` - rounds to the nearest integer, away from 0
- ``sin`` - the sine function
- ``sinh`` - the hyperbolic sine
- ``sqrt`` - the square root - (can also be written as ``x ^ 0.5``)
- ``tan`` - the tangent
- ``tanh`` - the hyperbolic tangent
``abs``
the absolute value, with positive sign
``acos``
arc cosine
``asin``
arc sine
``atan``
arc tangent
``atan2``
arc tangent of two variables
``bitand``, ``bitor`` and ``bitxor``
perform bitwise operations.
These will throw away any non-integer parts andd interpret the rest as an int.
``ceil``
round number up to nearest integer
``cos``
the cosine
``cosh``
hyperbolic cosine
``exp``
the base-e exponential function
``fac``
factorial - also known as ``x!`` (``x * (x - 1) * (x - 2) * ... * 1``)
``floor``
round number down to nearest integer
``ln``
the base-e logarithm
``log`` or ``log10``
the base-10 logarithm
``log2``
the base-2 logarithm
``max``
returns the larger of two numbers
``min``
returns the smaller of two numbers
``ncr``
"from n choose r" combination function - how many subsets of size r can be taken from n (order doesn't matter)
``npr``
the number of subsets of size r that can be taken from a set of n elements (including different order)
``pow(x,y)``
returns x to the y (and can be written as ``x ^ y``)
``round``
rounds to the nearest integer, away from 0
``sin``
the sine function
``sinh``
the hyperbolic sine
``sqrt``
the square root - (can also be written as ``x ^ 0.5``)
``tan``
the tangent
``tanh``
the hyperbolic tangent
All of the trigonometric functions use radians (the pi-based scale, not 360°).

12
doc_src/cmds/nextd.rst
View File

@ -6,18 +6,20 @@ nextd - move forward through directory history
Synopsis
--------
::
.. synopsis::
nextd [ -l | --list ] [POS]
nextd [-l | --list] [POS]
Description
-----------
``nextd`` moves forwards ``POS`` positions in the :ref:`history of visited directories <directory-history>`; if the end of the history has been hit, a warning is printed.
``nextd`` moves forwards *POS* positions in the :ref:`history of visited directories <directory-history>`; if the end of the history has been hit, a warning is printed.
If the ``-l`` or ``--list`` flag is specified, the current directory history is also displayed.
If the **-l** or **--list** option is specified, the current directory history is also displayed.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates.
The **-h** or **--help** option displays help about using this command.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the :envvar:`dirprev` and :envvar:`dirnext` variables which this command manipulates.
Example
-------

5
doc_src/cmds/not.rst
View File

@ -6,9 +6,9 @@ not - negate the exit status of a job
Synopsis
--------
::
.. synopsis::
not COMMAND [OPTIONS...]
not COMMAND [OPTIONS ...]
Description
@ -16,6 +16,7 @@ Description
``not`` negates the exit status of another command. If the exit status is zero, ``not`` returns 1. Otherwise, ``not`` returns 0.
The **-h** or **--help** option displays help about using this command.
Example
-------

4
doc_src/cmds/open.rst
View File

@ -6,9 +6,9 @@ open - open file in its default application
Synopsis
--------
::
.. synopsis::
open FILES...
open FILES ...
Description

4
doc_src/cmds/or.rst
View File

@ -6,7 +6,7 @@ or - conditionally execute a command
Synopsis
--------
::
.. synopsis::
COMMAND1; or COMMAND2
@ -19,6 +19,8 @@ Description
``or`` does not change the current exit status itself, but the command it runs most likely will. The exit status of the last foreground command to exit can always be accessed using the :ref:`$status <variables-status>` variable.
The **-h** or **--help** option displays help about using this command.
Example
-------

4
doc_src/cmds/popd.rst
View File

@ -6,7 +6,7 @@ popd - move through directory stack
Synopsis
--------
::
.. synopsis::
popd
@ -15,6 +15,8 @@ Description
``popd`` removes the top directory from the :ref:`directory stack <directory-stack>` and changes the working directory to the new top directory. Use :ref:`pushd <cmd-pushd>` to add directories to the stack.
The **-h** or **--help** option displays help about using this command.
Example
-------

12
doc_src/cmds/prevd.rst
View File

@ -6,18 +6,20 @@ prevd - move backward through directory history
Synopsis
--------
::
.. synopsis::
prevd [ -l | --list ] [POS]
prevd [-l | --list] [POS]
Description
-----------
``prevd`` moves backwards ``POS`` positions in the :ref:`history of visited directories <directory-history>`; if the beginning of the history has been hit, a warning is printed.
``prevd`` moves backwards *POS* positions in the :ref:`history of visited directories <directory-history>`; if the beginning of the history has been hit, a warning is printed.
If the ``-l`` or ``--list`` flag is specified, the current history is also displayed.
If the **-l** or **--list** flag is specified, the current history is also displayed.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates.
Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the :envvar:`dirprev` and :envvar:`dirnext` variables which this command manipulates.
The **-h** or **--help** option displays help about using this command.
Example
-------

6
doc_src/cmds/printf.rst
View File

@ -6,7 +6,7 @@ printf - display text according to a format string
Synopsis
--------
::
.. synopsis::
printf FORMAT [ARGUMENT ...]
@ -19,9 +19,9 @@ Description
To see the documentation on the ``printf`` command you might have,
use ``command man printf``.
printf uses the format string FORMAT to print the ARGUMENT arguments. This means that it takes format specifiers in the format string and replaces each with an argument.
``printf`` uses the format string *FORMAT* to print the *ARGUMENT* arguments. This means that it takes format specifiers in the format string and replaces each with an argument.
The ``format`` argument is re-used as many times as necessary to convert all of the given arguments. So ``printf %s\n flounder catfish clownfish shark`` will print four lines.
The *FORMAT* argument is re-used as many times as necessary to convert all of the given arguments. So ``printf %s\n flounder catfish clownfish shark`` will print four lines.
Unlike :ref:`echo <cmd-echo>`, ``printf`` does not append a new line unless it is specified as part of the string.

31
doc_src/cmds/prompt_hostname.rst Normal file
View File

@ -0,0 +1,31 @@
.. _cmd-prompt_hostname:
prompt_hostname - print the hostname, shortened for use in the prompt
=====================================================================
Synopsis
--------
.. synopsis::
prompt_hostname
Description
-----------
``prompt_hostname`` prints a shortened version the current hostname for use in the prompt. It will print just the first component of the hostname, everything up to the first dot.
Examples
--------
::
function fish_prompt
echo -n (whoami)@(prompt_hostname) (prompt_pwd) '$ '
end
::
# The machine's full hostname is foo.bar.com
>_ prompt_hostname
foo

19
doc_src/cmds/prompt_login.rst
View File

@ -6,20 +6,23 @@ prompt_login - describe the login suitable for prompt
Synopsis
--------
.. synopsis::
prompt_login
Description
-----------
``prompt_login`` is a function to describe the current login. It will show the user, the host and also whether the shell is running in a chroot (currently Debian's ``debian_chroot`` file is supported).
Examples
--------
::
function fish_prompt
echo -n (prompt_login) (prompt_pwd) '$ '
end
Description
-----------
``prompt_login`` is a function to describe the current login. It will show the user, the host and also whether the shell is running in a chroot (currently debian's debian_chroot is supported).
Examples
--------
::
>_ prompt_login

23
doc_src/cmds/prompt_pwd.rst
View File

@ -6,29 +6,32 @@ prompt_pwd - print pwd suitable for prompt
Synopsis
--------
::
.. synopsis::
function fish_prompt
echo -n (prompt_pwd) '$ '
end
prompt_pwd
Description
-----------
``prompt_pwd`` is a function to print the current working directory in a way suitable for prompts. It will replace the home directory with "~" and shorten every path component but the last to a default of one character.
To change the number of characters per path component, pass ``--dir-length=`` or set ``$fish_prompt_pwd_dir_length`` to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely. This defaults to 1.
To change the number of characters per path component, pass ``--dir-length=`` or set :envvar:`fish_prompt_pwd_dir_length` to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely. This defaults to 1.
To keep some components unshortened, pass ``--full-length-dirs=`` or set ``$fish_prompt_pwd_full_dirs`` to the number of components. This defaults to 1, keeping the last component.
To keep some components unshortened, pass ``--full-length-dirs=`` or set :envvar:`$fish_prompt_pwd_full_dirs` to the number of components. This defaults to 1, keeping the last component.
If any positional arguments are given, prompt_pwd shortens them instead of $PWD.
If any positional arguments are given, ``prompt_pwd`` shortens them instead of $PWD.
Options
-------
- ``-h`` or ``--help`` displays the help and exits
- ``-d`` or ``--dir-length=MAX`` causes the components to be shortened to MAX characters each. This overrides $fish_prompt_pwd_dir_length.
- ``-D`` or ``--full-length-dirs=NUM`` keeps NUM components (counted from the right) as full length without shortening. This overrides $fish_prompt_pwd_full_dirs.
**-d** or **--dir-length** *MAX*
Causes the components to be shortened to *MAX* characters each. This overrides :envvar:`fish_prompt_pwd_dir_length`.
**-D** or **--full-length-dirs** *NUM*
Keeps *NUM* components (counted from the right) as full length without shortening. This overrides :envvar:`fish_prompt_pwd_full_dirs`.
**-h** or **--help**
Displays help about using this command.
Examples
--------

16
doc_src/cmds/psub.rst
View File

@ -6,9 +6,9 @@ psub - perform process substitution
Synopsis
--------
::
.. synopsis::
COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [-s SUFFIX])
COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [(-s | --suffix) SUFFIX] )
Description
-----------
@ -17,11 +17,17 @@ Some shells (e.g., ksh, bash) feature a syntax that is a mix between command sub
The following options are available:
- ``-f`` or ``--file`` will cause psub to use a regular file instead of a named pipe to communicate with the calling process. This will cause ``psub`` to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream. This is the default.
**-f** or **--file**
Use a regular file instead of a named pipe to communicate with the calling process. This will cause ``psub`` to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream. This is the default.
- ``-F`` or ``--fifo`` will cause psub to use a named pipe rather than a file. You should only use this if the command produces no more than 8 KiB of output. The limit on the amount of data a FIFO can buffer varies with the OS but is typically 8 KiB, 16 KiB or 64 KiB. If you use this option and the command on the left of the psub pipeline produces more output a deadlock is likely to occur.
**-F** or **--fifo**
Use a named pipe rather than a file. You should only use this if the command produces no more than 8 KiB of output. The limit on the amount of data a FIFO can buffer varies with the OS but is typically 8 KiB, 16 KiB or 64 KiB. If you use this option and the command on the left of the psub pipeline produces more output a deadlock is likely to occur.
- ``-s`` or ``--suffix`` will append SUFFIX to the filename.
**-s** or **--suffix** *SUFFIX*
Append SUFFIX to the filename.
**-h** or **--help**
Displays help about using this command.
Example
-------

8
doc_src/cmds/pushd.rst
View File

@ -6,14 +6,14 @@ pushd - push directory to directory stack
Synopsis
--------
::
.. synopsis::
pushd [DIRECTORY]
pushd DIRECTORY
Description
-----------
The ``pushd`` function adds ``DIRECTORY`` to the top of the :ref:`directory stack <directory-stack>` and makes it the current working directory. :ref:`popd <cmd-popd>` will pop it off and return to the original directory.
The ``pushd`` function adds *DIRECTORY* to the top of the :ref:`directory stack <directory-stack>` and makes it the current working directory. :ref:`popd <cmd-popd>` will pop it off and return to the original directory.
Without arguments, it exchanges the top two directories in the stack.
@ -21,6 +21,8 @@ Without arguments, it exchanges the top two directories in the stack.
``pushd -NUMBER`` rotates clockwise i.e. top to bottom.
The **-h** or **--help** option displays help about using this command.
Example
-------

14
doc_src/cmds/pwd.rst
View File

@ -6,9 +6,10 @@ pwd - output the current working directory
Synopsis
--------
::
.. synopsis::
pwd [(-P | --physical)] [(-L | --logical)]
pwd [-P | --physical]
pwd [-L | --logical]
Description
@ -24,9 +25,14 @@ Description
The following options are available:
- ``-L`` or ``--logical`` Output the logical working directory, without resolving symlinks (default behavior).
**-L** or **--logical**
Output the logical working directory, without resolving symlinks (default behavior).
- ``-P`` or ``--physical`` Output the physical working directory, with symlinks resolved.
**-P** or **--physical**
Output the physical working directory, with symlinks resolved.
**-h** or **--help**
Displays help about using this command.
See Also
--------

12
doc_src/cmds/random.rst
View File

@ -6,30 +6,34 @@ random - generate random number
Synopsis
--------
::
.. synopsis::
random
random SEED
random START END
random START STEP END
random choice [ITEMS...]
random choice [ITEMS ...]
Description
-----------
``random`` generates a pseudo-random integer from a uniform distribution. The
range (inclusive) depends on the arguments.
No arguments indicate a range of 0 to 32767 (inclusive).
If one argument is specified, the internal engine will be seeded with the
argument for future invocations of ``random`` and no output will be produced.
Two arguments indicate a range from START to END (both START and END included).
Two arguments indicate a range from *START* to *END* (both *START* and *END* included).
Three arguments indicate a range from START to END with a spacing of STEP
Three arguments indicate a range from *START* to *END* with a spacing of *STEP*
between possible outputs.
``random choice`` will select one random item from the succeeding arguments.
The **-h** or **--help** option displays help about using this command.
Note that seeding the engine will NOT give the same result across different
systems.

67
doc_src/cmds/read.rst
View File

@ -6,55 +6,72 @@ read - read line of input into variables
Synopsis
--------
::
.. synopsis::
read [OPTIONS] [VARIABLE ...]
Description
-----------
``read`` reads from standard input and either writes the result back to standard output (for use in command substitution), or stores the result in one or more shell variables. By default, ``read`` reads a single line and splits it into variables on spaces or tabs. Alternatively, a null character or a maximum number of characters can be used to terminate the input, and other delimiters can be given. Unlike other shells, there is no default variable (such as ``REPLY``) for storing the result - instead, it is printed on standard output.
``read`` reads from standard input and either writes the result back to standard output (for use in command substitution), or stores the result in one or more shell variables. By default, ``read`` reads a single line and splits it into variables on spaces or tabs. Alternatively, a null character or a maximum number of characters can be used to terminate the input, and other delimiters can be given. Unlike other shells, there is no default variable (such as :envvar:`REPLY`) for storing the result - instead, it is printed on standard output.
The following options are available:
- ``-c CMD`` or ``--command=CMD`` sets the initial string in the interactive mode command buffer to ``CMD``.
**-c** *CMD* or **--command** *CMD*
Sets the initial string in the interactive mode command buffer to *CMD*.
- ``-d DELIMITER`` or ``--delimiter=DELIMITER`` splits on DELIMITER. DELIMITER will be used as an entire string to split on, not a set of characters.
**-d** or **--delimiter** *DELIMITER*
Splits on *DELIMITER*. *DELIMITER* will be used as an entire string to split on, not a set of characters.
- ``-g`` or ``--global`` makes the variables global.
**-g** or **--global**
Makes the variables global.
- ``-s`` or ``--silent`` masks characters written to the terminal, replacing them with asterisks. This is useful for reading things like passwords or other sensitive information.
**-s** or **--silent**
Masks characters written to the terminal, replacing them with asterisks. This is useful for reading things like passwords or other sensitive information.
- ``-f`` or ``--function`` scopes the variable to the currently executing function. It is erased when the function ends.
**-f** or **--function**
Scopes the variable to the currently executing function. It is erased when the function ends.
- ``-l`` or ``--local`` scopes the variable to the currently executing block. It is erased when the block ends. Outside of a block, this is the same as ``--function``.
**-l** or **--local**
Scopes the variable to the currently executing block. It is erased when the block ends. Outside of a block, this is the same as **--function**.
- ``-n NCHARS`` or ``--nchars=NCHARS`` makes ``read`` return after reading NCHARS characters or the end of
the line, whichever comes first.
**-n** or **--nchars** *NCHARS*
Makes ``read`` return after reading *NCHARS* characters or the end of the line, whichever comes first.
- ``-p PROMPT_CMD`` or ``--prompt=PROMPT_CMD`` uses the output of the shell command ``PROMPT_CMD`` as the prompt for the interactive mode. The default prompt command is ``set_color green; echo read; set_color normal; echo "> "``
**-p** or **--prompt** *PROMPT_CMD*
Uses the output of the shell command *PROMPT_CMD* as the prompt for the interactive mode. The default prompt command is ``set_color green; echo read; set_color normal; echo "> "``
- ``-P PROMPT_STR`` or ``--prompt-str=PROMPT_STR`` uses the string as the prompt for the interactive mode. It is equivalent to ``echo PROMPT_STR`` and is provided solely to avoid the need to frame the prompt as a command. All special characters in the string are automatically escaped before being passed to the :ref:`echo <cmd-echo>` command.
**-P** or **--prompt-str** *PROMPT_STR*
Uses the *PROMPT_STR* as the prompt for the interactive mode. It is equivalent to ``echo $PROMPT_STR`` and is provided solely to avoid the need to frame the prompt as a command. All special characters in the string are automatically escaped before being passed to the :ref:`echo <cmd-echo>` command.
- ``-R RIGHT_PROMPT_CMD`` or ``--right-prompt=RIGHT_PROMPT_CMD`` uses the output of the shell command ``RIGHT_PROMPT_CMD`` as the right prompt for the interactive mode. There is no default right prompt command.
**-R** or **--right-prompt** *RIGHT_PROMPT_CMD*
Uses the output of the shell command *RIGHT_PROMPT_CMD* as the right prompt for the interactive mode. There is no default right prompt command.
- ``-S`` or ``--shell`` enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode. NOTE: Prior to fish 3.0, the short opt for ``--shell`` was ``-s``, but it has been changed for compatibility with bash's ``-s`` short opt for ``--silent``.
**-S** or **--shell**
Enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode. NOTE: Prior to fish 3.0, the short opt for **--shell** was **-s**, but it has been changed for compatibility with bash's **-s** short opt for **--silent**.
- ``-t`` -or ``--tokenize`` causes read to split the input into variables by the shell's tokenization rules. This means it will honor quotes and escaping. This option is of course incompatible with other options to control splitting like ``--delimiter`` and does not honor $IFS (like fish's tokenizer). It saves the tokens in the manner they'd be passed to commands on the commandline, so e.g. ``a\ b`` is stored as ``a b``. Note that currently it leaves command substitutions intact along with the parentheses.
**-t** -or **--tokenize**
Causes read to split the input into variables by the shell's tokenization rules. This means it will honor quotes and escaping. This option is of course incompatible with other options to control splitting like **--delimiter** and does not honor :envvar:`IFS` (like fish's tokenizer). It saves the tokens in the manner they'd be passed to commands on the commandline, so e.g. ``a\ b`` is stored as ``a b``. Note that currently it leaves command substitutions intact along with the parentheses.
- ``-u`` or ``--unexport`` prevents the variables from being exported to child processes (default behaviour).
**-u** or **--unexport**
Prevents the variables from being exported to child processes (default behaviour).
- ``-U`` or ``--universal`` causes the specified shell variable to be made universal.
**-U** or **--universal**
Causes the specified shell variable to be made universal.
- ``-x`` or ``--export`` exports the variables to child processes.
**-x** or **--export**
Exports the variables to child processes.
- ``-a`` or ``--list`` stores the result as a list in a single variable. This option is also available as ``--array`` for backwards compatibility.
**-a** or **--list**
Stores the result as a list in a single variable. This option is also available as **--array** for backwards compatibility.
- ``-z`` or ``--null`` marks the end of the line with the NUL character, instead of newline. This also disables interactive mode.
**-z** or **--null**
Marks the end of the line with the NUL character, instead of newline. This also disables interactive mode.
- ``-L`` or ``--line`` reads each line into successive variables, and stops after each variable has been filled. This cannot be combined with the ``--delimiter`` option.
**-L** or **--line**
Reads each line into successive variables, and stops after each variable has been filled. This cannot be combined with the ``--delimiter`` option.
Without the ``--line`` option, ``read`` reads a single line of input from standard input, breaks it into tokens, and then assigns one token to each variable specified in ``VARIABLES``. If there are more tokens than variables, the complete remainder is assigned to the last variable.
Without the ``--line`` option, ``read`` reads a single line of input from standard input, breaks it into tokens, and then assigns one token to each variable specified in *VARIABLES*. If there are more tokens than variables, the complete remainder is assigned to the last variable.
If no option to determine how to split like ``--delimiter``, ``--line`` or ``--tokenize`` is given, the variable ``IFS`` is used as a list of characters to split on. Relying on the use of ``IFS`` is deprecated and this behaviour will be removed in future versions. The default value of ``IFS`` contains space, tab and newline characters. As a special case, if ``IFS`` is set to the empty string, each character of the input is considered a separate token.
@ -74,14 +91,14 @@ When ``read`` reaches the end-of-file (EOF) instead of the terminator, the exit
Otherwise, it is set to 0.
In order to protect the shell from consuming too many system resources, ``read`` will only consume a
maximum of 100 MiB (104857600 bytes); if the terminator is not reached before this limit then VARIABLE
maximum of 100 MiB (104857600 bytes); if the terminator is not reached before this limit then *VARIABLE*
is set to empty and the exit status is set to 122. This limit can be altered with the
``fish_read_limit`` variable. If set to 0 (zero), the limit is removed.
:envvar:`fish_read_limit` variable. If set to 0 (zero), the limit is removed.
Example
-------
The following code stores the value 'hello' in the shell variable ``$foo``.
The following code stores the value 'hello' in the shell variable :envvar:`$foo`.

Some files were not shown because too many files have changed in this diff Show More