fish-shell/doc_src/cmds/fish.rst

.. _cmd-fish:

fish - the friendly interactive shell
=====================================

Synopsis
--------

::

    fish [OPTIONS] [-c command] [FILE] [ARGUMENTS...]

Description
-----------

fish is a command-line shell written mainly with interactive use in mind. This page briefly describes the options for invoking fish. The :ref:`full manual <intro>` is available in HTML by using the :ref:`help <cmd-help>` command from inside fish, and in the `fish-doc(1)` man page. The :ref:`tutorial <tutorial>` is available as HTML via ``help tutorial`` or in `fish-tutorial(1)`.

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 :ref:`$argv <variables-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 ``--init-command=COMMANDS`` evaluate the specified commands after reading the configuration, before running the 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.

- ``-o`` or ``--debug-output=DEBUG_FILE`` specify a file path to receive the debug output, including categories and ``fish_trace``. The default is stderr.

- ``-i`` or ``--interactive`` specify that fish is to run in interactive mode

- ``-l`` or ``--login`` specify that fish is to run as a login shell

- ``-n`` or ``--no-execute`` do not execute any commands, only perform syntax checking

- ``-p`` or ``--profile=PROFILE_FILE`` when fish exits, output timing information on all executed commands to the specified file

- ``-P`` or ``--private`` enables :ref:`private mode <private-mode>`, so fish will not access old or store new history.

- ``--print-rusage-self`` when fish exits, output stats from getrusage

- ``--print-debug-categories`` outputs the list of debug categories, and then exits.

- ``-v`` or ``--version`` display version and exit

- ``-D`` or ``--debug-stack-frames=DEBUG_LEVEL`` specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.

- ``-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.

The fish exit status is generally the :ref:`exit status of the last foreground command <variables-status>`.

.. _debugging-fish:

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. 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. 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::

    > fish --debug='complete,*history*' --debug-output=/tmp/fish.log --init-command='set fish_trace on'
docs: Add labels to all commands This allows us to use :ref: references, which don't require hardcoding it as html [ci skip] 2019-03-31 17:05:09 +08:00			`.. _cmd-fish:`

Switch command docs from \section to reStructuredText 2018-12-17 09:39:33 +08:00			`fish - the friendly interactive shell`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`=====================================`
Switch command docs from \section to reStructuredText 2018-12-17 09:39:33 +08:00
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00			`Synopsis`
			`--------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
docs: update all command synopsis formatting Adds synopses for those commands missing them. Moves all synopsis sections to code blocks. This improves the appearance, although highlighting as fish code may not be the ideal appearance. 2019-09-17 17:59:04 +08:00			`::`
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00
Read arguments with `fish -c` This reads any additional positional arguments given to `fish -c` into $argv. We don't handle the first argument specially (as `$0`) as that's confusing and doesn't seem very useful. Fixes #2314. 2020-09-26 20:45:51 +08:00			`fish [OPTIONS] [-c command] [FILE] [ARGUMENTS...]`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Convert \\subsection sections into rst format 2018-12-19 10:44:30 +08:00			`Description`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`-----------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Add fish debugging examples 2020-05-16 06:54:45 +08:00			fish is a command-line shell written mainly with interactive use in mind. This page briefly describes the options for invoking fish. The :ref:`full manual <intro>` is available in HTML by using the :ref:`help <cmd-help>` command from inside fish, and in the `fish-doc(1)` man page. The :ref:`tutorial <tutorial>` is available as HTML via ``help tutorial`` or in `fish-tutorial(1)`.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
			`The following options are available:`

Read arguments with `fish -c` This reads any additional positional arguments given to `fish -c` into $argv. We don't handle the first argument specially (as `$0`) as that's confusing and doesn't seem very useful. Fixes #2314. 2020-09-26 20:45:51 +08:00			- ``-c`` or ``--command=COMMANDS`` evaluate the specified commands instead of reading from the commandline, passing any additional positional arguments via :ref:`$argv <variables-argv>`. Note that, unlike other shells, the first argument is not the name of the program (``$0``), but simply the first normal argument.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-C`` or ``--init-command=COMMANDS`` evaluate the specified commands after reading the configuration, before running the command specified by ``-c`` or reading interactive input
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Add fish debugging examples 2020-05-16 06:54:45 +08:00			- ``-d`` or ``--debug=DEBUG_CATEGORIES`` enable debug output and specify a pattern for matching debug categories. See :ref:`Debugging <debugging-fish>` below for details.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Add fish debugging examples 2020-05-16 06:54:45 +08:00			- ``-o`` or ``--debug-output=DEBUG_FILE`` specify a file path to receive the debug output, including categories and ``fish_trace``. The default is stderr.
Introduce the fish log, a replacement for debug() This adds a new mechanism for logging, intended to replace debug(). The entry points are FLOG and FLOGF. FLOG can be used to log a sequence of arguments, FLOGF is for printf-style formatted strings. Each call to FLOG and FLOGF requires a category. If logging for a category is not enabled, there is no effect (and arguments are not evaluated). Categories may be enabled on the command line via the -d option. 2019-04-20 15:15:51 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-i`` or ``--interactive`` specify that fish is to run in interactive mode
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-l`` or ``--login`` specify that fish is to run as a login shell
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-n`` or ``--no-execute`` do not execute any commands, only perform syntax checking
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-p`` or ``--profile=PROFILE_FILE`` when fish exits, output timing information on all executed commands to the specified file
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
docs/cmds/fish: Document private mode there as well Oversight, see #2376. [ci skip] 2019-06-30 19:54:03 +08:00			- ``-P`` or ``--private`` enables :ref:`private mode <private-mode>`, so fish will not access old or store new history.

Add print-rusage-self to fish This adds an option --print-rusage-self to the fish executable. When set, this option prints some getrusage stats to the console in a human-readable way. This will be used by upcoming benchmarking support. 2019-04-11 04:58:29 +08:00			- ``--print-rusage-self`` when fish exits, output stats from getrusage

Introduce the fish log, a replacement for debug() This adds a new mechanism for logging, intended to replace debug(). The entry points are FLOG and FLOGF. FLOG can be used to log a sequence of arguments, FLOGF is for printf-style formatted strings. Each call to FLOG and FLOGF requires a category. If logging for a category is not enabled, there is no effect (and arguments are not evaluated). Categories may be enabled on the command line via the -d option. 2019-04-20 15:15:51 +08:00			- ``--print-debug-categories`` outputs the list of debug categories, and then exits.

Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-v`` or ``--version`` display version and exit
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-D`` or ``--debug-stack-frames=DEBUG_LEVEL`` specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
doc: add link to feature flags in fish command [ci skip] 2019-10-07 19:13:04 +08:00			- ``-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.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
fish --help: remove outdated information about exit status 2020-05-16 16:33:13 +08:00			The fish exit status is generally the :ref:`exit status of the last foreground command <variables-status>`.
Add fish debugging examples 2020-05-16 06:54:45 +08:00
			`.. _debugging-fish:`

			`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. 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. 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::

			`> fish --debug='complete,history' --debug-output=/tmp/fish.log --init-command='set fish_trace on'`