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

- ``-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=CATEGORY_GLOB`` enables debug output and specifies a glob for matching debug categories (like ``fish -d``). Defaults to empty.

- ``-o`` or ``--debug-output=path`` 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 exit status of the last foreground command. If fish is exiting because of a parse error, the exit status is 127.
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
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			`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
docs: Link to the fish-doc and fish-tutorial pages from fish(1) Just a brief explanation what that page is good for and how to get the full scoop. Fixes #5521. [ci skip] 2019-12-12 03:58:24 +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:`

Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-c`` or ``--command=COMMANDS`` evaluate the specified commands instead of reading from the commandline
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
Improve the docs from DEBUG_LEVEL to CATEGORY_GLOB This stuff still isn't documented properly. 2019-06-18 00:07:43 +08:00			- ``-d`` or ``--debug=CATEGORY_GLOB`` enables debug output and specifies a glob for matching debug categories (like ``fish -d``). Defaults to empty.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Add support for fish_trace variable to trace execution This adds support for `fish_trace`, a new variable intended to serve the same purpose as `set -x` as in bash. Setting this variable to anything non-empty causes execution to be traced. In the future we may give more specific meaning to the value of the variable. The user's prompt is not traced unless you run it explicitly. Events are also not traced because it is noisy; however autoloading is. Fixes #3427 2019-10-19 09:08:22 +08:00			- ``-o`` or ``--debug-output=path`` 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
			`The fish exit status is generally the exit status of the last foreground command. If fish is exiting because of a parse error, the exit status is 127.`