Mirrors/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell synced 2024-11-10 15:14:44 +00:00
Code Issues Projects Releases Packages Wiki Activity

Fix command section separator line lengths

Browse source
This commit is contained in:
ridiculousfish 2019-01-02 20:10:47 -08:00
parent 0e936198db
commit c8dc306b18
85 changed files with 287 additions and 287 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
sphinx_doc_src/cmds/abbr.rst
View file

@ -1,5 +1,5 @@
abbr - manage fish abbreviations
==========================================
================================
Synopsis
--------
@ -11,14 +11,14 @@ abbr --show
abbr --list
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 @key{Space} or @key{Enter}, the full text ``git checkout`` will appear in the command line.
Options
------------
-------
The following options are available:
@ -40,7 +40,7 @@ In addition, when adding abbreviations:
See the "Internals" section for more on them.
Examples
------------
--------
@ -83,7 +83,7 @@ Erase the ``gco`` abbreviation.
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.
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:

6
sphinx_doc_src/cmds/alias.rst
View file

@ -1,5 +1,5 @@
alias - create a function
==========================================
=========================
Synopsis
--------
@ -10,7 +10,7 @@ alias [OPTIONS] NAME=DEFINITION
Description
------------
-----------
``alias`` is a simple wrapper for the ``function`` builtin, which creates a function wrapping a command. It has similar syntax to POSIX shell ``alias``. For other uses, it is recommended to define a <a href='#function'>function</a>.
@ -28,7 +28,7 @@ The following options are available:
- ``-s`` or ``--save`` Automatically save the function created by the alias into your fish configuration directory using <a href='#funcsave'>funcsave</a>.
Example
------------
-------
The following code will create ``rmi``, which runs ``rm`` with additional arguments on every invocation.

6
sphinx_doc_src/cmds/and.rst
View file

@ -1,5 +1,5 @@
and - conditionally execute a command
==========================================
=====================================
Synopsis
--------
@ -8,7 +8,7 @@ COMMAND1; and COMMAND2
Description
------------
-----------
``and`` is used to execute a command if the previous command was successful (returned a status of 0).
@ -17,7 +17,7 @@ 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 <a href="index.html#variables-status">$status</a> variable.
Example
------------
-------
The following code runs the ``make`` command to build a program. If the build succeeds, ``make``'s exit status is 0, and the program is installed. If either step fails, the exit status is 1, and ``make clean`` is run, which removes the files created by the build process.

16
sphinx_doc_src/cmds/argparse.rst
View file

@ -1,5 +1,5 @@
argparse - parse options passed to a fish script or function
==========================================
============================================================
Synopsis
--------
@ -8,7 +8,7 @@ argparse [OPTIONS] OPTION_SPEC... -- [ARG...]
Description
------------
-----------
This command makes it easy for fish scripts and functions to handle arguments in a manner 100% identical to how fish builtin commands handle their arguments. You pass a sequence of arguments that define the options recognized, followed by a literal ``--``, then the arguments to be parsed (which might also include a literal ``--``). More on this in the <a href="#argparse-usage">usage</a> section below.
@ -19,7 +19,7 @@ Each option that is seen in the ARG list will result in a var name of the form `
For example ``_flag_h`` and ``_flag_help`` if ``-h`` or ``--help`` is seen. The var 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, does not have an associated value) the values are the short and long flags seen. If the option is not a boolean flag 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 var will not be set.
Options
------------
-------
The following ``argparse`` options are available. They must appear before all OPTION_SPECs:
@ -36,7 +36,7 @@ The following ``argparse`` options are available. They must appear before all OP
- ``-h`` or ``--help`` displays help about using this command.
Usage
------------
-----
Using this command involves passing two sets of arguments separated by ``--``. The first set consists of one or more option specifications (``OPTION_SPEC`` above) and options that modify the behavior of ``argparse``. These must be listed before the ``--`` argument. The second set are the arguments to be parsed in accordance with the option specifications. They occur after the ``--`` argument and can be empty. More about this below but here is a simple example that might be used in a function named ``my_function``:
@ -73,7 +73,7 @@ But this is not:
The first ``--`` seen is what allows the ``argparse`` command to reliably separate the option specifications from the command arguments.
Option Specifications
------------
---------------------
Each option specification is a string composed of
@ -98,7 +98,7 @@ See the <a href="#fish-opt">``fish_opt``</a> command for a friendlier but more v
In the following examples if a flag is not seen when parsing the arguments then the corresponding _flag_X var(s) will not be set.
Flag Value Validation
------------
---------------------
It is common to want to validate the the value provided for an option satisfies some criteria. For example, that it is a valid integer within a specific range. You can always do this after ``argparse`` returns but you can also request that ``argparse`` perform the validation by executing arbitrary fish script. To do so simply append an ``!`` (exclamation-mark) then the fish script to be run. When that code is executed three vars will be defined:
@ -115,7 +115,7 @@ The script should write any error messages to stdout, not stderr. It should retu
Fish ships with a ``_validate_int`` function that accepts a ``--min`` and ``--max`` flag. Let's say your command accepts a ``-m`` or ``--max`` flag and the minimum allowable value is zero and the maximum is 5. You would define the option like this: ``m/max=!_validate_int --min 0 --max 5``. The default if you just call ``_validate_int`` without those flags is to simply check that the value is a valid integer with no limits on the min or max value allowed.
Example OPTION_SPECs
------------
--------------------
Some OPTION_SPEC examples:
@ -144,6 +144,6 @@ After parsing the arguments the ``argv`` var is set with local scope to any valu
If an error occurs during argparse processing it will exit with a non-zero status and print error messages to stderr.
Notes
------------
-----
Prior to the addition of this builtin command in the 2.7.0 release there were two main ways to parse the arguments passed to a fish script or function. One way was to use the OS provided ``getopt`` command. The problem with that is that the GNU and BSD implementations are not compatible. Which makes using that external command difficult other than in trivial situations. The other way is to iterate over ``$argv`` and use the fish ``switch`` statement to decide how to handle the argument. That, however, involves a huge amount of boilerplate code. It is also borderline impossible to implement the same behavior as builtin commands.

6
sphinx_doc_src/cmds/begin.rst
View file

@ -1,5 +1,5 @@
begin - start a new block of code
==========================================
=================================
Synopsis
--------
@ -8,7 +8,7 @@ begin; [COMMANDS...;] end
Description
------------
-----------
``begin`` is used to create a new block of code.
@ -20,7 +20,7 @@ The block is unconditionally executed. ``begin; ...; end`` is equivalent to ``if
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.

6
sphinx_doc_src/cmds/bg.rst
View file

@ -1,5 +1,5 @@
bg - send jobs to background
==========================================
============================
Synopsis
--------
@ -8,7 +8,7 @@ bg [PID...]
Description
------------
-----------
``bg`` sends <a href="index.html#syntax-job-control">jobs</a> to the background, resuming them if they are stopped.
@ -20,7 +20,7 @@ When at least one of the arguments isn't a valid job specifier (i.e. PID),
When all arguments are valid job specifiers, bg will background all matching jobs that exist.
Example
------------
-------
``bg 123 456 789`` will background 123, 456 and 789.

10
sphinx_doc_src/cmds/bind.rst
View file

@ -1,5 +1,5 @@
bind - handle fish key bindings
==========================================
===============================
Synopsis
--------
@ -17,7 +17,7 @@ bind (-e | --erase) [(-M | --mode) MODE]
Description
------------
-----------
``bind`` adds a binding for the specified key sequence to the specified command.
@ -62,7 +62,7 @@ The following parameters are available:
- ``--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. ``--preset`` should only be used in full binding sets (like when working on ``fish_vi_key_bindings``).
Special input functions
------------
-----------------------
The following special input functions are available:
- ``accept-autosuggestion``, accept the current autosuggestion completely
@ -147,7 +147,7 @@ The following special input functions are available:
Examples
------------
--------
@ -176,7 +176,7 @@ Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line.
Special Case: The escape Character
------------
----------------------------------
The escape key can be used standalone, for example, to switch from insertion mode to normal mode when using Vi keybindings. Escape may also be used as a "meta" key, to indicate the start of an escape sequence, such as function or arrow keys. Custom bindings can also be defined that begin with an escape character.

8
sphinx_doc_src/cmds/block.rst
View file

@ -1,5 +1,5 @@
block - temporarily block delivery of events
==========================================
============================================
Synopsis
--------
@ -8,7 +8,7 @@ block [OPTIONS...]
Description
------------
-----------
``block`` prevents events triggered by ``fish`` or the <a href="commands.html#emit">``emit``</a> command from being delivered and acted upon while the block is in place.
@ -28,7 +28,7 @@ The following parameters are available:
Example
------------
-------
@ -49,6 +49,6 @@ Example
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.

6
sphinx_doc_src/cmds/break.rst
View file

@ -1,5 +1,5 @@
break - stop the current inner loop
==========================================
===================================
Synopsis
--------
@ -8,7 +8,7 @@ LOOP_CONSTRUCT; [COMMANDS...] break; [COMMANDS...] end
Description
------------
-----------
``break`` halts a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
@ -16,7 +16,7 @@ There are no parameters for ``break``.
Example
------------
-------
The following code searches all .c files for "smurf", and halts at the first occurrence.

4
sphinx_doc_src/cmds/breakpoint.rst
View file

@ -1,5 +1,5 @@
breakpoint - Launch debug mode
==========================================
==============================
Synopsis
--------
@ -8,7 +8,7 @@ breakpoint
Description
------------
-----------
``breakpoint`` is used to halt a running script and launch an interactive debugging prompt.

6
sphinx_doc_src/cmds/builtin.rst
View file

@ -1,5 +1,5 @@
builtin - run a builtin command
==========================================
===============================
Synopsis
--------
@ -8,7 +8,7 @@ builtin BUILTINNAME [OPTIONS...]
Description
------------
-----------
``builtin`` forces the shell to use a builtin command, rather than a function or program.
@ -18,7 +18,7 @@ The following parameters are available:
Example
------------
-------

6
sphinx_doc_src/cmds/case.rst
View file

@ -1,5 +1,5 @@
case - conditionally execute a block of commands
==========================================
================================================
Synopsis
--------
@ -8,7 +8,7 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
Description
------------
-----------
``switch`` executes one of several blocks of commands, depending on whether a specified value matches one of several values. ``case`` is used together with the ``switch`` statement in order to determine which block should be executed.
@ -20,7 +20,7 @@ Note that command substitutions in a case statement will be evaluated even if it
Example
------------
-------
Say \$animal contains the name of an animal. Then this code would classify it:

8
sphinx_doc_src/cmds/cd.rst
View file

@ -1,5 +1,5 @@
cd - change directory
==========================================
=====================
Synopsis
--------
@ -8,7 +8,7 @@ cd [DIRECTORY]
Description
------------
-----------
``cd`` changes the current working directory.
If ``DIRECTORY`` is supplied, it will become the new directory. If no parameter is given, the contents of the ``HOME`` environment variable will be used.
@ -22,7 +22,7 @@ Fish also ships a wrapper function around the builtin ``cd`` that understands ``
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.
Examples
------------
--------
@ -36,6 +36,6 @@ Examples
See Also
------------
--------
See also the <a href="commands.html#cdh">``cdh``</a> command for changing to a recently visited directory.

6
sphinx_doc_src/cmds/cdh.rst
View file

@ -1,5 +1,5 @@
cdh - change to a recently visited directory
==========================================
============================================
Synopsis
@ -9,13 +9,13 @@ cdh [ directory ]
Description
------------
-----------
``cdh`` with no arguments presents a list of recently visited directories. You can then select one of the entries by letter or number. You can also press @key{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.
See Also
------------
--------
See also the <a href="commands.html#prevd">``prevd``</a> and <a href="commands.html#pushd">``pushd``</a> commands which also work with the recent ``cd`` history and are provided for compatibility with other shells.

6
sphinx_doc_src/cmds/command.rst
View file

@ -1,5 +1,5 @@
command - run a program
==========================================
=======================
Synopsis
--------
@ -8,7 +8,7 @@ command [OPTIONS] COMMANDNAME [ARGS...]
Description
------------
-----------
``command`` forces the shell to execute the program ``COMMANDNAME`` and ignore any functions or builtins with the same name.
@ -25,7 +25,7 @@ With the ``-s`` option, ``command`` treats every argument as a separate command
For basic compatibility with POSIX ``command``, the ``-v`` flag is recognized as an alias for ``-s``.
Examples
------------
--------
``command ls`` causes fish to execute the ``ls`` program, even if an ``ls`` function exists.

6
sphinx_doc_src/cmds/commandline.rst
View file

@ -1,5 +1,5 @@
commandline - set or get the current command line buffer
==========================================
========================================================
Synopsis
--------
@ -8,7 +8,7 @@ commandline [OPTIONS] [CMD]
Description
------------
-----------
``commandline`` can be used to set or get the current contents of the command line buffer.
@ -60,7 +60,7 @@ The following options output metadata about the commandline state:
Example
------------
-------
``commandline -j $history[3]`` replaces the job under the cursor with the third item from the command line history.

6
sphinx_doc_src/cmds/complete.rst
View file

@ -1,5 +1,5 @@
complete - edit command specific tab-completions
==========================================
================================================
Synopsis
--------
@ -21,7 +21,7 @@ complete ( -C[STRING] | --do-complete[=STRING] )
Description
------------
-----------
For an introduction to specifying completions, see <a
href='index.html#completion-own'>Writing your own completions</a> in
@ -95,7 +95,7 @@ When erasing completions, it is possible to either erase all completions for a s
Example
------------
-------
The short style option ``-o`` for the ``gcc`` command requires that a file follows it. This can be done using writing:

6
sphinx_doc_src/cmds/contains.rst
View file

@ -1,5 +1,5 @@
contains - test if a word is present in a list
==========================================
==============================================
Synopsis
--------
@ -8,7 +8,7 @@ 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.
@ -19,7 +19,7 @@ The following options are available:
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.
Example
------------
-------
If $animals is a list of animals, the following will test if it contains a cat:

6
sphinx_doc_src/cmds/continue.rst
View file

@ -1,5 +1,5 @@
continue - skip the remainder of the current iteration of the current inner loop
==========================================
================================================================================
Synopsis
--------
@ -8,12 +8,12 @@ LOOP_CONSTRUCT; [COMMANDS...;] continue; [COMMANDS...;] end
Description
------------
-----------
``continue`` skips the remainder of the current iteration of the current inner loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.
Example
------------
-------
The following code removes all tmp files that do not contain the word smurf.

6
sphinx_doc_src/cmds/count.rst
View file

@ -1,5 +1,5 @@
count - count the number of elements of an array
==========================================
================================================
Synopsis
--------
@ -8,7 +8,7 @@ count $VARIABLE
Description
------------
-----------
``count`` prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains.
@ -18,7 +18,7 @@ Description
Example
------------
-------

4
sphinx_doc_src/cmds/dirh.rst
View file

@ -1,5 +1,5 @@
dirh - print directory history
==========================================
==============================
Synopsis
--------
@ -8,7 +8,7 @@ dirh
Description
------------
-----------
``dirh`` prints the current directory history. The current position in the history is highlighted using the color defined in the ``fish_color_history_current`` environment variable.

4
sphinx_doc_src/cmds/dirs.rst
View file

@ -1,5 +1,5 @@
dirs - print directory stack
==========================================
============================
Synopsis
--------
@ -9,7 +9,7 @@ dirs -c
Description
------------
-----------
``dirs`` prints the current directory stack, as created by the <a href="#pushd">``pushd``</a> command.

6
sphinx_doc_src/cmds/disown.rst
View file

@ -1,5 +1,5 @@
disown - remove a process from the list of jobs
==========================================
===============================================
Synopsis
--------
@ -8,7 +8,7 @@ disown [ PID ... ]
Description
------------
-----------
``disown`` removes the specified <a href="index.html#syntax-job-control">job</a> from the list of jobs. The job itself continues to exist, but fish does not keep track of it any longer.
@ -21,7 +21,7 @@ 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.
Example
------------
-------
``firefox &; disown`` will start the Firefox web browser in the background and remove it from the job list, meaning it will not be closed when the fish process is closed.

8
sphinx_doc_src/cmds/echo.rst
View file

@ -1,5 +1,5 @@
echo - display a line of text
==========================================
=============================
Synopsis
--------
@ -8,7 +8,7 @@ echo [OPTIONS] [STRING]
Description
------------
-----------
``echo`` displays a string of text.
@ -23,7 +23,7 @@ The following options are available:
- ``-e``, Enable interpretation of backslash escapes
Escape Sequences
------------
----------------
If ``-e`` is used, the following sequences are recognized:
@ -52,7 +52,7 @@ If ``-e`` is used, the following sequences are recognized:
- ``\xHH`` byte with hexadecimal value HH (1 to 2 digits)
Example
------------
-------

6
sphinx_doc_src/cmds/else.rst
View file

@ -1,5 +1,5 @@
else - execute command if a condition is not met
==========================================
================================================
Synopsis
--------
@ -8,13 +8,13 @@ if CONDITION; COMMANDS_TRUE...; [else; COMMANDS_FALSE...;] end
Description
------------
-----------
``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.

8
sphinx_doc_src/cmds/emit.rst
View file

@ -1,5 +1,5 @@
emit - Emit a generic event
==========================================
===========================
Synopsis
--------
@ -8,13 +8,13 @@ emit EVENT_NAME [ARGUMENTS...]
Description
------------
-----------
``emit`` emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments.
Example
------------
-------
The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type.
@ -31,6 +31,6 @@ The following code first defines an event handler for the generic event named 't
Notes
------------
-----
Note that events are only sent to the current fish process as there is no way to send events from one fish process to another.

4
sphinx_doc_src/cmds/end.rst
View file

@ -1,5 +1,5 @@
end - end a block of commands.
==========================================
==============================
Synopsis
--------
@ -12,7 +12,7 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
Description
------------
-----------
``end`` ends a block of commands.

6
sphinx_doc_src/cmds/eval.rst
View file

@ -1,5 +1,5 @@
eval - evaluate the specified commands
==========================================
======================================
Synopsis
--------
@ -8,13 +8,13 @@ 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.
If your command does not need access to stdin, consider using ``source`` instead.
Example
------------
-------
The following code will call the ls command. Note that ``fish`` does not support the use of shell variables as direct commands; ``eval`` can be used to work around this.

6
sphinx_doc_src/cmds/exec.rst
View file

@ -1,5 +1,5 @@
exec - execute command in current process
==========================================
=========================================
Synopsis
--------
@ -8,12 +8,12 @@ exec COMMAND [OPTIONS...]
Description
------------
-----------
``exec`` replaces the currently running shell with a new command. On successful completion, ``exec`` never returns. ``exec`` cannot be used inside a pipeline.
Example
------------
-------
``exec emacs`` starts up the emacs text editor, and exits ``fish``. When emacs exits, the session will terminate.

4
sphinx_doc_src/cmds/exit.rst
View file

@ -1,5 +1,5 @@
exit - exit the shell
==========================================
=====================
Synopsis
--------
@ -8,7 +8,7 @@ exit [STATUS]
Description
------------
-----------
``exit`` causes fish to exit. If ``STATUS`` is supplied, it will be converted to an integer and used as the exit code. Otherwise, the exit code will be that of the last command executed.

4
sphinx_doc_src/cmds/false.rst
View file

@ -1,5 +1,5 @@
false - return an unsuccessful result
==========================================
=====================================
Synopsis
--------
@ -8,6 +8,6 @@ false
Description
------------
-----------
``false`` sets the exit status to 1.

6
sphinx_doc_src/cmds/fg.rst
View file

@ -1,5 +1,5 @@
fg - bring job to foreground
==========================================
============================
Synopsis
--------
@ -8,12 +8,12 @@ fg [PID]
Description
------------
-----------
``fg`` brings the specified <a href="index.html#syntax-job-control">job</a> 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 with the specified group ID is put in the foreground.
Example
------------
-------
``fg`` will put the last job in the foreground.

4
sphinx_doc_src/cmds/fish.rst
View file

@ -1,5 +1,5 @@
fish - the friendly interactive shell
==========================================
=====================================
Synopsis
--------
@ -8,7 +8,7 @@ fish [OPTIONS] [-c command] [FILE [ARGUMENTS...]]
Description
------------
-----------
``fish`` is a command-line shell written mainly with interactive use in mind. The full manual is available <a href='index.html'>in HTML</a> by using the <a href='#help'>help</a> command from inside fish.

6
sphinx_doc_src/cmds/fish_breakpoint_prompt.rst
View file

@ -1,5 +1,5 @@
fish_breakpoint_prompt - define the appearance of the command line prompt when in the context of a ``breakpoint`` command
==========================================
=========================================================================================================================
Synopsis
--------
@ -10,7 +10,7 @@ end
Description
------------
-----------
By defining the ``fish_breakpoint_prompt`` function, the user can choose a custom prompt when asking for input in response to a ``breakpoint`` command. The ``fish_breakpoint_prompt`` function is executed when the prompt is to be shown, and the output is used as a prompt.
@ -20,7 +20,7 @@ The exit status of commands within ``fish_breakpoint_prompt`` will not modify th
Example
------------
-------
A simple prompt that is a simplified version of the default debugging prompt:

6
sphinx_doc_src/cmds/fish_config.rst
View file

@ -1,9 +1,9 @@
fish_config - start the web-based configuration interface
==========================================
=========================================================
Description
------------
-----------
``fish_config`` starts the web-based configuration interface.
@ -17,6 +17,6 @@ If the ``BROWSER`` environment variable is set, it will be used as the name of t
Example
------------
-------
``fish_config`` opens a new web browser window and allows you to configure certain fish settings.

4
sphinx_doc_src/cmds/fish_indent.rst
View file

@ -1,5 +1,5 @@
fish_indent - indenter and prettifier
==========================================
=====================================
Synopsis
--------
@ -8,7 +8,7 @@ fish_indent [OPTIONS]
Description
------------
-----------
``fish_indent`` is used to indent a piece of fish code. ``fish_indent`` reads commands from standard input and outputs them to standard output or a specified file.

6
sphinx_doc_src/cmds/fish_key_reader.rst
View file

@ -1,5 +1,5 @@
fish_key_reader - explore what characters keyboard keys send
==========================================
============================================================
Synopsis
--------
@ -8,7 +8,7 @@ fish_key_reader [OPTIONS]
Description
------------
-----------
``fish_key_reader`` is used to study input received from the terminal and can help with key binds. The program is interactive and works on standard input. Individual characters themselves and their hexadecimal values are displayed.
@ -27,7 +27,7 @@ The following options are available:
- ``-v`` or ``--version`` prints fish_key_reader's version and exits.
Usage Notes
------------
-----------
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``.

6
sphinx_doc_src/cmds/fish_mode_prompt.rst
View file

@ -1,18 +1,18 @@
fish_mode_prompt - define the appearance of the mode indicator
==========================================
==============================================================
The fish_mode_prompt function will output the mode indicator for use in vi-mode.
Description
------------
-----------
The default ``fish_mode_prompt`` function will output indicators about the current Vi editor mode displayed to the left of the regular prompt. Define your own function to customize the appearance of the mode indicator. You can also define an empty ``fish_mode_prompt`` function to remove the Vi mode indicators. The ``$fish_bind_mode variable`` can be used to determine the current mode. It
will be one of ``default``, ``insert``, ``replace_one``, or ``visual``.
Example
------------
-------

6
sphinx_doc_src/cmds/fish_opt.rst
View file

@ -1,5 +1,5 @@
fish_opt - create an option spec for the argparse command
==========================================
=========================================================
Synopsis
--------
@ -10,7 +10,7 @@ fish_opt ( -s X | --short=X ) [ -l LONG | --long=LONG ] [ --long-only ] \
Description
------------
-----------
This command provides a way to produce option specifications suitable for use with the <a href="#argparse">``argparse``</a> 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.
@ -31,7 +31,7 @@ The following ``argparse`` options are available:
- ``-h`` or ``--help`` displays help about using this command.
Examples
------------
--------
Define a single option spec for the boolean help flag:

6
sphinx_doc_src/cmds/fish_prompt.rst
View file

@ -1,5 +1,5 @@
fish_prompt - define the appearance of the command line prompt
==========================================
==============================================================
Synopsis
--------
@ -10,7 +10,7 @@ end
Description
------------
-----------
By defining the ``fish_prompt`` function, the user can choose a custom prompt. The ``fish_prompt`` function is executed when the prompt is to be shown, and the output is used as a prompt.
@ -20,7 +20,7 @@ The exit status of commands within ``fish_prompt`` will not modify the value of
Example
------------
-------
A simple prompt:

6
sphinx_doc_src/cmds/fish_right_prompt.rst
View file

@ -1,5 +1,5 @@
fish_right_prompt - define the appearance of the right-side command line prompt
==========================================
===============================================================================
Synopsis
--------
@ -10,7 +10,7 @@ end
Description
------------
-----------
``fish_right_prompt`` is similar to ``fish_prompt``, except that it appears on the right side of the terminal window.
@ -18,7 +18,7 @@ Multiple lines are not supported in ``fish_right_prompt``.
Example
------------
-------
A simple right prompt:

4
sphinx_doc_src/cmds/fish_update_completions.rst
View file

@ -1,9 +1,9 @@
fish_update_completions - Update completions using manual pages
==========================================
===============================================================
Description
------------
-----------
``fish_update_completions`` parses manual pages installed on the system, and attempts to create completion files in the ``fish`` configuration directory.

4
sphinx_doc_src/cmds/fish_vi_mode.rst
View file

@ -1,5 +1,5 @@
fish_vi_mode - Enable vi mode
==========================================
=============================
Synopsis
--------
@ -8,7 +8,7 @@ fish_vi_mode
Description
------------
-----------
This function is deprecated. Please call ``fish_vi_key_bindings directly``

8
sphinx_doc_src/cmds/for.rst
View file

@ -1,5 +1,5 @@
for - perform a set of commands multiple times.
==========================================
===============================================
Synopsis
--------
@ -8,12 +8,12 @@ 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.
Example
------------
-------
@ -28,7 +28,7 @@ Example
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:

4
sphinx_doc_src/cmds/funced.rst
View file

@ -1,5 +1,5 @@
funced - edit a function interactively
==========================================
======================================
Synopsis
--------
@ -8,7 +8,7 @@ funced [OPTIONS] NAME
Description
------------
-----------
``funced`` provides an interface to edit the definition of the function ``NAME``.

4
sphinx_doc_src/cmds/funcsave.rst
View file

@ -1,5 +1,5 @@
funcsave - save the definition of a function to the user's autoload directory
==========================================
=============================================================================
Synopsis
--------
@ -8,7 +8,7 @@ funcsave FUNCTION_NAME
Description
------------
-----------
``funcsave`` saves the current definition of a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use.

8
sphinx_doc_src/cmds/function.rst
View file

@ -1,5 +1,5 @@
function - create a function
==========================================
============================
Synopsis
--------
@ -8,7 +8,7 @@ function NAME [OPTIONS]; BODY; end
Description
------------
-----------
``function`` creates a new function ``NAME`` with the body ``BODY``.
@ -58,7 +58,7 @@ By using one of the event handler switches, a function can be made to run automa
- ``fish_exit`` is emitted right before fish exits.
Example
------------
-------
@ -110,6 +110,6 @@ This will beep when the most recent job completes.
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.

6
sphinx_doc_src/cmds/functions.rst
View file

@ -1,5 +1,5 @@
functions - print or erase functions
==========================================
====================================
Synopsis
--------
@ -12,7 +12,7 @@ functions [ -e | -q ] FUNCTIONS...
Description
------------
-----------
``functions`` prints or erases functions.
@ -60,7 +60,7 @@ The exit status of ``functions`` is the number of functions specified in the arg
Examples
------------
--------
::

6
sphinx_doc_src/cmds/help.rst
View file

@ -1,5 +1,5 @@
help - display fish documentation
==========================================
=================================
Synopsis
--------
@ -8,7 +8,7 @@ help [SECTION]
Description
------------
-----------
``help`` displays the fish help documentation.
@ -22,6 +22,6 @@ Note that most builtin commands display their help in the terminal when given th
Example
------------
-------
``help fg`` shows the documentation for the ``fg`` builtin.

10
sphinx_doc_src/cmds/history.rst
View file

@ -1,5 +1,5 @@
history - Show and manipulate command history
==========================================
=============================================
Synopsis
--------
@ -13,7 +13,7 @@ history ( -h | --help )
Description
------------
-----------
``history`` is used to search, delete, and otherwise manipulate the history of interactive commands.
@ -52,7 +52,7 @@ These flags can appear before or immediately after one of the sub-commands liste
- ``-h`` or ``--help`` display help for this command.
Example
------------
-------
@ -70,7 +70,7 @@ Example
Customizing the name of the history file
------------
----------------------------------------
By default interactive commands are logged to ``$XDG_DATA_HOME/fish/fish_history`` (typically ``~/.local/share/fish/fish_history``).
@ -81,7 +81,7 @@ You can change ``fish_history`` at any time (by using ``set -x fish_history "ses
Other shells such as bash and zsh use a variable named ``HISTFILE`` for a similar purpose. Fish uses a different name to avoid conflicts and signal that the behavior is different (session name instead of a file path). Also, if you set the var to anything other than ``fish`` or ``default`` it will inhibit importing the bash history. That's because the most common use case for this feature is to avoid leaking private or sensitive history when giving a presentation.
Notes
------------
-----
If you specify both ``--prefix`` and ``--contains`` the last flag seen is used.

6
sphinx_doc_src/cmds/if.rst
View file

@ -1,5 +1,5 @@
if - conditionally execute a command
==========================================
====================================
Synopsis
--------
@ -11,7 +11,7 @@ end
Description
------------
-----------
``if`` will execute the command ``CONDITION``. If the condition's exit status is 0, the commands ``COMMANDS_TRUE`` will execute. If the exit status is not 0 and ``else`` is given, ``COMMANDS_FALSE`` will be executed.
@ -20,7 +20,7 @@ You can use <a href="#and">``and``</a> or <a href="#or">``or``</a> in the condit
The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.
Example
------------
-------
The following code will print ``foo.txt exists`` if the file foo.txt exists and is a regular file, otherwise it will print ``bar.txt exists`` if the file bar.txt exists and is a regular file, otherwise it will print ``foo.txt and bar.txt do not exist``.

6
sphinx_doc_src/cmds/isatty.rst
View file

@ -1,5 +1,5 @@
isatty - test if a file descriptor is a tty.
==========================================
============================================
Synopsis
--------
@ -8,7 +8,7 @@ isatty [FILE DESCRIPTOR]
Description
------------
-----------
``isatty`` tests if a file descriptor is a tty.
@ -18,7 +18,7 @@ If the specified file descriptor is a tty, the exit status of the command is zer
Examples
------------
--------
From an interactive shell, the commands below exit with a return value of zero:

8
sphinx_doc_src/cmds/jobs.rst
View file

@ -1,5 +1,5 @@
jobs - print currently running jobs
==========================================
===================================
Synopsis
--------
@ -8,7 +8,7 @@ jobs [OPTIONS] [PID]
Description
------------
-----------
``jobs`` prints a list of the currently running <a href="index.html#syntax-job-control">jobs</a> and their status.
@ -29,10 +29,10 @@ On systems that supports this feature, jobs will print the CPU usage of each job
The exit code of the ``jobs`` builtin is ``0`` if there are running background jobs and ``1`` otherwise.
no output.
------------
----------
Example
------------
-------
``jobs`` outputs a summary of the current jobs.

18
sphinx_doc_src/cmds/math.rst
View file

@ -1,5 +1,5 @@
math - Perform mathematics calculations
==========================================
=======================================
Synopsis
--------
@ -8,7 +8,7 @@ math [-sN | --scale=N] [--] EXPRESSION
Description
------------
-----------
``math`` is used to perform mathematical calculations. It supports all the usual operations such as addition, subtraction, etc. As well as functions like ``abs()``, ``sqrt()`` and ``log2()``.
@ -23,19 +23,19 @@ The following options are available:
- ``-sN`` or ``--scale=N`` sets the scale of the result. ``N`` must be an integer. 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.
Return Values
------------
-------------
If the expression is successfully evaluated and doesn't over/underflow or return NaN the return ``status`` is zero (success) else one.
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``) is also available.
Operators
------------
---------
``math`` knows the following operators:
@ -52,7 +52,7 @@ Operators
They are all used in an infix manner - ``5 + 2``, not ``+ 5 2``.
Constants
------------
---------
``math`` knows the following constants:
@ -62,7 +62,7 @@ Constants
Use them without a leading ``$`` - ``pi - 3`` should be about 0.
Functions
------------
---------
``math`` supports the following functions:
@ -92,7 +92,7 @@ Functions
All of the trigonometric functions use radians.
Examples
------------
--------
``math 1+1`` outputs 2.
@ -107,7 +107,7 @@ Examples
``math "sin(pi)"`` outputs ``0``.
Compatibility notes
------------
-------------------
Fish 1.x and 2.x releases relied on the ``bc`` command for handling ``math`` expressions. Starting with fish 3.0.0 fish uses the tinyexpr library and evaluates the expression without the involvement of any external commands.

6
sphinx_doc_src/cmds/nextd.rst
View file

@ -1,5 +1,5 @@
nextd - move forward through directory history
==========================================
==============================================
Synopsis
--------
@ -8,7 +8,7 @@ nextd [ -l | --list ] [POS]
Description
------------
-----------
``nextd`` moves forwards ``POS`` positions in the history of visited directories; if the end of the history has been hit, a warning is printed.
@ -19,7 +19,7 @@ Note that the ``cd`` command limits directory history to the 25 most recently vi
You may be interested in the <a href="commands.html#cdh">``cdh``</a> command which provides a more intuitive way to navigate to recently visited directories.
Example
------------
-------

6
sphinx_doc_src/cmds/not.rst
View file

@ -1,5 +1,5 @@
not - negate the exit status of a job
==========================================
=====================================
Synopsis
--------
@ -8,13 +8,13 @@ not COMMAND [OPTIONS...]
Description
------------
-----------
``not`` negates the exit status of another command. If the exit status is zero, ``not`` returns 1. Otherwise, ``not`` returns 0.
Example
------------
-------
The following code reports an error and exits if no file named spoon can be found.

6
sphinx_doc_src/cmds/open.rst
View file

@ -1,5 +1,5 @@
open - open file in its default application
==========================================
===========================================
Synopsis
--------
@ -8,7 +8,7 @@ open FILES...
Description
------------
-----------
``open`` opens a file in its default application, using the appropriate tool for the operating system. On GNU/Linux, this requires the common but optional ``xdg-open`` utility, from the ``xdg-utils`` package.
@ -16,6 +16,6 @@ Note that this function will not be used if a command by this name exists (which
Example
------------
-------
``open *.txt`` opens all the text files in the current directory using your system's default text editor.

6
sphinx_doc_src/cmds/or.rst
View file

@ -1,5 +1,5 @@
or - conditionally execute a command
==========================================
====================================
Synopsis
--------
@ -8,7 +8,7 @@ COMMAND1; or COMMAND2
Description
------------
-----------
``or`` is used to execute a command if the previous command was not successful (returned a status of something other than 0).
@ -18,7 +18,7 @@ for <a href="#if">``if``</a> and <a href="#while">``while``</a> for examples.
``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 <a href="index.html#variables-status">$status</a> variable.
Example
------------
-------
The following code runs the ``make`` command to build a program. If the build succeeds, the program is installed. If either step fails, ``make clean`` is run, which removes the files created by the build process.

6
sphinx_doc_src/cmds/popd.rst
View file

@ -1,5 +1,5 @@
popd - move through directory stack
==========================================
===================================
Synopsis
--------
@ -8,14 +8,14 @@ popd
Description
------------
-----------
``popd`` removes the top directory from the directory stack and changes the working directory to the new top directory. Use <a href="#pushd">``pushd``</a> to add directories to the stack.
You may be interested in the <a href="commands.html#cdh">``cdh``</a> command which provides a more intuitive way to navigate to recently visited directories.
Example
------------
-------

6
sphinx_doc_src/cmds/prevd.rst
View file

@ -1,5 +1,5 @@
prevd - move backward through directory history
==========================================
===============================================
Synopsis
--------
@ -8,7 +8,7 @@ prevd [ -l | --list ] [POS]
Description
------------
-----------
``prevd`` moves backwards ``POS`` positions in the history of visited directories; if the beginning of the history has been hit, a warning is printed.
@ -19,7 +19,7 @@ Note that the ``cd`` command limits directory history to the 25 most recently vi
You may be interested in the <a href="commands.html#cdh">``cdh``</a> command which provides a more intuitive way to navigate to recently visited directories.
Example
------------
-------

6
sphinx_doc_src/cmds/printf.rst
View file

@ -1,5 +1,5 @@
printf - display text according to a format string
==========================================
==================================================
Synopsis
--------
@ -8,7 +8,7 @@ printf format [argument...]
Description
------------
-----------
printf formats the string FORMAT with ARGUMENT, and displays the result.
The string FORMAT should contain format specifiers, each of which are replaced with successive arguments according to the specifier. Specifiers are detailed below, and are taken from the C library function ``printf(3)``.
@ -61,7 +61,7 @@ The ``format`` argument is re-used as many times as necessary to convert all of
This file has been imported from the printf in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try ``command printf``.
Example
------------
-------

4
sphinx_doc_src/cmds/prompt_pwd.rst
View file

@ -8,14 +8,14 @@ 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, set $fish_prompt_pwd_dir_length to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely.
Examples
------------
--------

6
sphinx_doc_src/cmds/psub.rst
View file

@ -1,5 +1,5 @@
psub - perform process substitution
==========================================
===================================
Synopsis
--------
@ -8,7 +8,7 @@ COMMAND1 ( COMMAND2 | psub [-F | --fifo] [-f | --file] [-s SUFFIX])
Description
------------
-----------
Some shells (e.g., ksh, bash) feature a syntax that is a mix between command substitution and piping, called process substitution. It is used to send the output of a command into the calling command, much like command substitution, but with the difference that the output is not sent through commandline arguments but through a named pipe, with the filename of the named pipe sent as an argument to the calling program. ``psub`` combined with a regular command substitution provides the same functionality.
@ -21,7 +21,7 @@ The following options are available:
- ``-s`` or ``--suffix`` will append SUFFIX to the filename.
Example
------------
-------

6
sphinx_doc_src/cmds/pushd.rst
View file

@ -1,5 +1,5 @@
pushd - push directory to directory stack
==========================================
=========================================
Synopsis
--------
@ -8,7 +8,7 @@ pushd [DIRECTORY]
Description
------------
-----------
The ``pushd`` function adds ``DIRECTORY`` to the top of the directory stack and makes it the current working directory. <a href="#popd">``popd``</a> will pop it off and return to the original directory.
@ -23,7 +23,7 @@ See also ``dirs`` and ``dirs -c``.
You may be interested in the <a href="commands.html#cdh">``cdh``</a> command which provides a more intuitive way to navigate to recently visited directories.
Example
------------
-------

2
sphinx_doc_src/cmds/pwd.rst
View file

@ -8,7 +8,7 @@ pwd
Description
------------
-----------
``pwd`` outputs (prints) the current working directory.

6
sphinx_doc_src/cmds/random.rst
View file

@ -1,5 +1,5 @@
random - generate random number
==========================================
===============================
Synopsis
--------
@ -12,7 +12,7 @@ random choice [ITEMS...]
Description
------------
-----------
``RANDOM`` generates a pseudo-random integer from a uniform distribution. The
range (inclusive) is dependent on the arguments passed.
@ -31,7 +31,7 @@ You should not consider ``RANDOM`` cryptographically secure, or even
statistically accurate.
Example
------------
-------
The following code will count down from a random even number between 10 and 20 to 1:

8
sphinx_doc_src/cmds/read.rst
View file

@ -1,5 +1,5 @@
read - read line of input into variables
==========================================
========================================
Synopsis
--------
@ -8,7 +8,7 @@ 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.
@ -73,12 +73,12 @@ is set to empty and the exit status is set to 122. This limit can be altered wit
``fish_read_limit`` variable. If set to 0 (zero), the limit is removed.
Using another read history file
------------
-------------------------------
The ``read`` command supported the ``-m`` and ``--mode-name`` flags in fish versions prior to 2.7.0 to specify an alternative read history file. Those flags are now deprecated and ignored. Instead, set the ``fish_history`` variable to specify a history session ID. That will affect both the ``read`` history file and the fish command history file. You can set it to an empty string to specify that no history should be read or written. This is useful for presentations where you do not want possibly private or sensitive history to be exposed to the audience but do want history relevant to the presentation to be available.
Example
------------
-------
The following code stores the value 'hello' in the shell variable ``$foo``.

4
sphinx_doc_src/cmds/realpath.rst
View file

@ -1,5 +1,5 @@
realpath - Convert a path to an absolute path without symlinks
==========================================
==============================================================
Synopsis
--------
@ -8,7 +8,7 @@ realpath path
Description
------------
-----------
This is implemented as a function and a builtin. The function will attempt to use an external realpath command if one can be found. Otherwise it falls back to the builtin. The builtin does not support any options. It's meant to be used only by scripts which need to be portable. The builtin implementation behaves like GNU realpath when invoked without any options (which is the most common use case). In general scripts should not invoke the builtin directly. They should just use ``realpath``.

6
sphinx_doc_src/cmds/return.rst
View file

@ -1,5 +1,5 @@
return - stop the current inner function
==========================================
========================================
Synopsis
--------
@ -8,7 +8,7 @@ function NAME; [COMMANDS...;] return [STATUS]; [COMMANDS...;] end
Description
------------
-----------
``return`` halts a currently running function. The exit status is set to ``STATUS`` if it is given.
@ -16,7 +16,7 @@ It is usually added inside of a conditional block such as an <a href="#if">if</a
Example
------------
-------
The following code is an implementation of the false command as a fish function

8
sphinx_doc_src/cmds/set.rst
View file

@ -1,5 +1,5 @@
set - display and change shell variables.
==========================================
=========================================
Synopsis
--------
@ -14,7 +14,7 @@ set ( -S | --show ) [SCOPE_OPTIONS] [VARIABLE_NAME]...
Description
------------
-----------
``set`` manipulates <a href="index.html#variables">shell variables</a>.
@ -84,7 +84,7 @@ In assignment mode, ``set`` does not modify the exit status. This allows simulta
Examples
------------
--------
::
@ -115,7 +115,7 @@ Examples
Notes
------------
-----
Fish versions prior to 3.0 supported the syntax ``set PATH[1] PATH[4] /bin /sbin``, which worked like
``set PATH[1 4] /bin /sbin``. This syntax was not widely used, and was ambiguous and inconsistent.

10
sphinx_doc_src/cmds/set_color.rst
View file

@ -1,5 +1,5 @@
set_color - set the terminal color
==========================================
==================================
Synopsis
--------
@ -8,7 +8,7 @@ set_color [OPTIONS] VALUE
Description
------------
-----------
``set_color`` is used to control the color and styling of text in the terminal. ``VALUE`` corresponds to a reserved color name such as *red* or a RGB color value given as 3 or 6 hexadecimal digits. The *br*-, as in 'bright', forms are full-brightness variants of the 8 standard-brightness colors on many terminals. *brblack* has higher brightness than *black* - towards gray. A special keyword *normal* resets text formatting to terminal defaults.
@ -32,7 +32,7 @@ The following options are available:
Using the *normal* keyword will reset foreground, background, and all formatting back to default.
Notes
------------
-----
1. Using the *normal* keyword will reset both background and foreground colors to whatever is the default for the terminal.
2. Setting the background color only affects subsequently written characters. Fish provides no way to set the background color for the entire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides.
@ -40,7 +40,7 @@ Notes
4. ``set_color`` works by printing sequences of characters to *stdout*. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit code of ``isatty stdout`` before using ``set_color`` can be useful to decide not to colorize output in a script.
Examples
------------
--------
@ -53,7 +53,7 @@ Examples
Terminal Capability Detection
------------
-----------------------------
Fish uses a heuristic to decide if a terminal supports the 256-color palette as opposed to the more limited 16 color palette of older terminals. Support can be forced on by setting ``fish_term256`` to *1*. If ``$TERM`` contains "256color" (e.g., *xterm-256color*), 256-color support is enabled. If ``$TERM`` contains *xterm*, 256 color support is enabled (except for MacOS: ``$TERM_PROGRAM`` and ``$TERM_PROGRAM_VERSION`` are used to detect Terminal.app from MacOS 10.6; support is disabled here it because it is known that it reports ``xterm`` and only supports 16 colors.

6
sphinx_doc_src/cmds/source.rst
View file

@ -1,5 +1,5 @@
source - evaluate contents of file.
==========================================
===================================
Synopsis
--------
@ -9,7 +9,7 @@ somecommand | source
Description
------------
-----------
``source`` evaluates the commands of the specified file in the current shell. This is different from starting a new process to perform the commands (i.e. ``fish < FILENAME``) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the ``$argv`` variable. The ``$argv`` variable will not include the name of the sourced file.
@ -21,7 +21,7 @@ The return status of ``source`` is the return status of the last job to execute.
Example
------------
-------

6
sphinx_doc_src/cmds/status.rst
View file

@ -1,5 +1,5 @@
status - query fish runtime information
==========================================
=======================================
Synopsis
--------
@ -24,7 +24,7 @@ status test-feature FEATURE
Description
------------
-----------
With no arguments, ``status`` displays a summary of the current login and job control status of the shell.
@ -64,7 +64,7 @@ The following operations (sub-commands) are available:
- ``test-feature FEATURE`` returns 0 when FEATURE is enabled, 1 if it is disabled, and 2 if it is not recognized.
Notes
------------
-----
For backwards compatibility each subcommand can also be specified as a long or short option. For example, rather than ``status is-login`` you can type ``status --is-login``. The flag forms are deprecated and may be removed in a future release (but not before fish 3.0).

40
sphinx_doc_src/cmds/string.rst
View file

@ -1,5 +1,5 @@
string - manipulate strings
==========================================
===========================
Synopsis
--------
@ -29,7 +29,7 @@ string upper [(-q | --quiet)] [STRING...]
Description
------------
-----------
``string`` performs operations on strings.
@ -42,7 +42,7 @@ Most subcommands accept a ``-q`` or ``--quiet`` switch, which suppresses the usu
The following subcommands are available.
"escape" subcommand
------------
-------------------
``string escape`` escapes each STRING in one of three ways. The first is ``--style=script``. This is the default. It alters the string such that it can be passed back to ``eval`` to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If ``-n`` or ``--no-quoted`` is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.
@ -55,7 +55,7 @@ The following subcommands are available.
``string unescape`` performs the inverse of the ``string escape`` command. If the string to be unescaped is not properly formatted it is ignored. For example, doing ``string unescape --style=var (string escape --style=var $str)`` will return the original string. There is no support for unescaping pcre2.
"join" subcommand
------------
-----------------
``string join`` joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise.
@ -64,17 +64,17 @@ The following subcommands are available.
``string join`` joins its STRING arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as ``sort -z``. Exit status: 0 if at least one join was performed, or 1 otherwise.
"length" subcommand
------------
-------------------
``string length`` reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise.
"lower" subcommand
------------
------------------
``string lower`` converts each string argument to lowercase. Exit status: 0 if at least one string was converted to lowercase, else 1. This means that in conjunction with the ``-q`` flag you can readily test whether a string is already lowercase.
"match" subcommand
------------
------------------
``string match`` tests each STRING against PATTERN and prints matching substrings. Only the first match for each STRING is reported unless ``-a`` or ``--all`` is given, in which case all matches are reported.
@ -91,12 +91,12 @@ If ``--invert`` or ``-v`` is used the selected lines will be only those which do
Exit status: 0 if at least one match was found, or 1 otherwise.
"repeat" subcommand
------------
-------------------
``string repeat`` repeats the STRING ``-n`` or ``--count`` times. The ``-m`` or ``--max`` option will limit the number of outputted char (excluding the newline). This option can be used by itself or in conjunction with ``--count``. If both ``--count`` and ``--max`` are present, max char will be outputed unless the final repeated string size is less than max, in that case, the string will repeat until count has been reached. Both ``--count`` and ``--max`` will accept a number greater than or equal to zero, in the case of zero, nothing will be outputed. If ``-N`` or ``--no-newline`` is given, the output won't contain a newline character at the end. Exit status: 0 if yielded string is not empty, 1 otherwise.
"replace" subcommand
------------
--------------------
``string replace`` is similar to ``string match`` but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched.
@ -107,7 +107,7 @@ If you specify the ``-f`` or ``--filter`` flag then each input string is printed
Exit status: 0 if at least one replacement was performed, or 1 otherwise.
"split" subcommand
------------
------------------
``string split`` splits each STRING on the separator SEP, which can be an empty string. If ``-m`` or ``--max`` is specified, at most MAX splits are done on each STRING. If ``-r`` or ``--right`` is given, splitting is performed right-to-left. This is useful in combination with ``-m`` or ``--max``. With ``-n`` or ``--no-empty``, empty results are excluded from consideration (e.g. ``hello\n\nworld`` would expand to two strings and not three). Exit status: 0 if at least one split was performed, or 1 otherwise.
@ -120,22 +120,22 @@ See also ``read --delimiter``.
``split0`` has the important property that its output is not further split when used in a command substitution, allowing for the command substitution to produce elements containing newlines. This is most useful when used with Unix tools that produce zero bytes, such as ``find -print0`` or ``sort -z``. See split0 examples below.
"sub" subcommand
------------
----------------
``string sub`` prints a substring of each string argument. The start of the substring can be specified with ``-s`` or ``--start`` followed by a 1-based index value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be specified with ``-l`` or ``--length``. If the length is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise.
"trim" subcommand
------------
-----------------
``string trim`` removes leading and trailing whitespace from each STRING. If ``-l`` or ``--left`` is given, only leading whitespace is removed. If ``-r`` or ``--right`` is given, only trailing whitespace is trimmed. The ``-c`` or ``--chars`` switch causes the characters in CHARS to be removed instead of whitespace. Exit status: 0 if at least one character was trimmed, or 1 otherwise.
"upper" subcommand
------------
------------------
``string upper`` converts each string argument to uppercase. Exit status: 0 if at least one string was converted to uppercase, else 1. This means that in conjunction with the ``-q`` flag you can readily test whether a string is already uppercase.
Regular Expressions
------------
-------------------
Both the ``match`` and ``replace`` subcommand support regular expressions when used with the ``-r`` or ``--regex`` option. The dialect is that of PCRE2.
@ -186,7 +186,7 @@ And some other things:
- ``|`` is "alternation", i.e. the "or".
Examples
------------
--------
@ -270,7 +270,7 @@ Examples
Match Glob Examples
------------
-------------------
@ -306,7 +306,7 @@ Match Glob Examples
Match Regex Examples
------------
--------------------
@ -362,7 +362,7 @@ Match Regex Examples
Replace Literal Examples
------------
------------------------
@ -381,7 +381,7 @@ Replace Literal Examples
Replace Regex Examples
------------
----------------------
@ -399,7 +399,7 @@ Replace Regex Examples
Repeat Examples
------------
---------------

4
sphinx_doc_src/cmds/suspend.rst
View file

@ -1,5 +1,5 @@
suspend - suspend the current shell
==========================================
===================================
Synopsis
--------
@ -8,7 +8,7 @@ suspend [--force]
Description
------------
-----------
``suspend`` suspends execution of the current shell by sending it a
SIGTSTP signal, returning to the controlling process. It can be

6
sphinx_doc_src/cmds/switch.rst
View file

@ -1,5 +1,5 @@
switch - conditionally execute a block of commands
==========================================
==================================================
Synopsis
--------
@ -8,7 +8,7 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end
Description
------------
-----------
``switch`` performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. ``case`` is used together with the ``switch`` statement in order to determine which block should be executed.
@ -20,7 +20,7 @@ Note that command substitutions in a case statement will be evaluated even if it
Example
------------
-------
If the variable \$animal contains the name of an animal, the following code would attempt to classify it:

16
sphinx_doc_src/cmds/test.rst
View file

@ -1,5 +1,5 @@
test - perform tests on files and text
==========================================
======================================
Synopsis
--------
@ -9,7 +9,7 @@ test [EXPRESSION]
Description
------------
-----------
Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments.
@ -20,7 +20,7 @@ This test is mostly POSIX-compatible.
When using a variable as an argument for a test operator you should almost always enclose it in double-quotes. There are only two situations it is safe to omit the quote marks. The first is when the argument is a literal string with no whitespace or other characters special to the shell (e.g., semicolon). For example, ``test -b /my/file``. The second is using a variable that expands to exactly one element including if that element is the empty string (e.g., ``set x ''``). If the variable is not set, set but with no value, or set to more than one value you must enclose it in double-quotes. For example, ``test "$x" = "$y"``. Since it is always safe to enclose variables in double-quotes when used as ``test`` arguments that is the recommended practice.
Operators for files and directories
------------
-----------------------------------
- ``-b FILE`` returns true if ``FILE`` is a block device.
@ -59,7 +59,7 @@ Operators for files and directories
- ``-x FILE`` returns true if ``FILE`` is marked as executable.
Operators for text strings
------------
--------------------------
- ``STRING1 = STRING2`` returns true if the strings ``STRING1`` and ``STRING2`` are identical.
@ -70,7 +70,7 @@ Operators for text strings
- ``-z STRING`` returns true if the length of ``STRING`` is zero.
Operators to compare and examine numbers
------------
----------------------------------------
- ``NUM1 -eq NUM2`` returns true if ``NUM1`` and ``NUM2`` are numerically equal.
@ -87,7 +87,7 @@ Operators to compare and examine numbers
Both integers and floating point numbers are supported.
Operators to combine expressions
------------
--------------------------------
- ``COND1 -a COND2`` returns true if both ``COND1`` and ``COND2`` are true.
@ -105,7 +105,7 @@ Expressions can be grouped using parentheses.
Examples
------------
--------
If the ``/tmp`` directory exists, copy the ``/etc/motd`` file to it:
@ -185,7 +185,7 @@ which is logically equivalent to the following:
Standards
------------
---------
``test`` implements a subset of the <a href="http://www.unix.com/man-page/POSIX/1/test/">IEEE Std 1003.1-2008 (POSIX.1) standard</a>. The following exceptions apply:

6
sphinx_doc_src/cmds/trap.rst
View file

@ -1,5 +1,5 @@
trap - perform an action when the shell receives a signal
==========================================
=========================================================
Synopsis
--------
@ -8,7 +8,7 @@ trap [OPTIONS] [[ARG] REASON ... ]
Description
------------
-----------
``trap`` is a wrapper around the fish event delivery framework. It exists for backwards compatibility with POSIX shells. For other uses, it is recommended to define an <a href='index.html#event'>event handler</a>.
@ -33,7 +33,7 @@ Signal names are case insensitive and the ``SIG`` prefix is optional.
The return status is 1 if any ``REASON`` is invalid; otherwise trap returns 0.
Example
------------
-------

4
sphinx_doc_src/cmds/true.rst
View file

@ -1,5 +1,5 @@
true - return a successful result
==========================================
=================================
Synopsis
--------
@ -8,6 +8,6 @@ true
Description
------------
-----------
``true`` sets the exit status to 0.

6
sphinx_doc_src/cmds/type.rst
View file

@ -1,5 +1,5 @@
type - indicate how a command would be interpreted
==========================================
==================================================
Synopsis
--------
@ -8,7 +8,7 @@ type [OPTIONS] NAME [NAME ...]
Description
------------
-----------
With no options, ``type`` indicates how each ``NAME`` would be interpreted if used as a command name.
@ -30,7 +30,7 @@ The ``-q``, ``-p``, ``-t`` and ``-P`` flags (and their long flag aliases) are mu
Example
------------
-------

6
sphinx_doc_src/cmds/ulimit.rst
View file

@ -1,5 +1,5 @@
ulimit - set or get resource usage limits
==========================================
=========================================
Synopsis
--------
@ -8,7 +8,7 @@ ulimit [OPTIONS] [LIMIT]
Description
------------
-----------
``ulimit`` builtin sets or outputs the resource usage limits of the shell and any processes spawned by it. If a new limit value is omitted, the current value of the limit of the resource is printed; otherwise, the specified limit is set to the new value.
@ -62,7 +62,7 @@ The ``fish`` implementation of ``ulimit`` should behave identically to the imple
Example
------------
-------
``ulimit -Hs 64`` sets the hard stack size limit to 64 kB.

6
sphinx_doc_src/cmds/umask.rst
View file

@ -1,5 +1,5 @@
umask - set or get the file creation mode mask
==========================================
==============================================
Synopsis
--------
@ -8,7 +8,7 @@ umask [OPTIONS] [MASK]
Description
------------
-----------
``umask`` displays and manipulates the "umask", or file creation mode mask, which is used to restrict the default access to files.
@ -40,6 +40,6 @@ Note that symbolic masks currently do not work as intended.
Example
------------
-------
``umask 177`` or ``umask u=rw`` sets the file creation mask to read and write for the owner and no permissions at all for any other users.

6
sphinx_doc_src/cmds/vared.rst
View file

@ -1,5 +1,5 @@
vared - interactively edit the value of an environment variable
==========================================
===============================================================
Synopsis
--------
@ -8,12 +8,12 @@ vared VARIABLE_NAME
Description
------------
-----------
``vared`` is used to interactively edit the value of an environment variable. Array variables as a whole can not be edited using ``vared``, but individual array elements can.
Example
------------
-------
``vared PATH[3]`` edits the third element of the PATH array

6
sphinx_doc_src/cmds/wait.rst
View file

@ -1,5 +1,5 @@
wait - wait for jobs to complete
==========================================
================================
Synopsis
--------
@ -8,7 +8,7 @@ wait [-n | --any] [PID | PROCESS_NAME] ...
Description
------------
-----------
``wait`` waits for child jobs to complete.
@ -18,7 +18,7 @@ Description
- If the ``-n`` / ``--any`` flag is provided, the command returns as soon as the first job completes. If it is not provided, it returns after all jobs complete.
Example
------------
-------

6
sphinx_doc_src/cmds/while.rst
View file

@ -1,5 +1,5 @@
while - perform a command multiple times
==========================================
========================================
Synopsis
--------
@ -8,7 +8,7 @@ while CONDITION; COMMANDS...; end
Description
------------
-----------
``while`` repeatedly executes ``CONDITION``, and if the exit status is 0, then executes ``COMMANDS``.
@ -20,7 +20,7 @@ The exit status of the loop is 0 otherwise.
You can use <a href="#and">``and``</a> or <a href="#or">``or``</a> for complex conditions. Even more complex control can be achieved with ``while true`` containing a <a href="#break">break</a>.
Example
------------
-------