h/fish-shell
1
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2026-05-24 05:41:14 -03:00
Code Issues Packages Projects Releases Wiki Activity

docs: standardise on definition lists for options

Browse Source 
Harmonizes the option listing including formatting in a similar manner to the
synopsis of each entry.
This commit is contained in:
David Adam
2022-03-11 23:56:20 +08:00
parent cf85bf9be3
commit e23e52a8e9
30 changed files with 470 additions and 240 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc_src/cmds/alias.rst
View File

@@ -27,9 +27,11 @@ You cannot create an alias to a function with the same name. Note that spaces ne
The following options are available:
- **-h** or **--help** displays help about using this command.
**-h** or **--help**
Displays help about using this command.
- **-s** or **--save** Automatically save the function created by the alias into your fish configuration directory using :ref:`funcsave <cmd-funcsave>`.
**-s** or **--save**
Saves the function created by the alias into your fish configuration directory using :ref:`funcsave <cmd-funcsave>`.
Example
-------

24
doc_src/cmds/argparse.rst
View File

@@ -25,22 +25,28 @@ The variables will be set with local scope (i.e., as if the script had done ``se
Options
-------
The following ``argparse`` options are available. They must appear before all OPTION_SPECs:
The following ``argparse`` options are available. They must appear before all *OPTION_SPEC*\ s:
**-n** or **--name**
the command name for use in error messages. By default the current function name will be used, or ``argparse`` if run outside of a function.
The command name for use in error messages. By default the current function name will be used, or ``argparse`` if run outside of a function.
**-x** or **--exclusive** should be followed by a comma separated list of short or long options that are mutually exclusive. You can use this more than once to define multiple sets of mutually exclusive options.
**-x** or **--exclusive** *OPTIONS*
A comma separated list of options that are mutually exclusive. You can use this more than once to define multiple sets of mutually exclusive options.
- **-N** or **--min-args** is followed by an integer that defines the minimum number of acceptable non-option arguments. The default is zero.
**-N** or **--min-args** *NUMBER*
The minimum number of acceptable non-option arguments. The default is zero.
- **-X** or **--max-args** is followed by an integer that defines the maximum number of acceptable non-option arguments. The default is infinity.
**-X** or **--max-args** *NUMBER*
The maximum number of acceptable non-option arguments. The default is infinity.
- **-i** or **--ignore-unknown** ignores unknown options, keeping them and their arguments in $argv instead.
**-i** or **--ignore-unknown**
Ignores unknown options, keeping them and their arguments in $argv instead.
- **-s** or **--stop-nonopt** causes scanning the arguments to stop as soon as the first non-option argument is seen. Among other things, this is useful to implement subcommands that have their own options.
**-s** or **--stop-nonopt**
Causes scanning the arguments to stop as soon as the first non-option argument is seen. Among other things, this is useful to implement subcommands that have their own options.
- **-h** or **--help** displays help about using this command.
**-h** or **--help**
Displays help about using this command.
.. _cmd-argparse-usage:
@@ -159,7 +165,7 @@ Fish ships with a ``_validate_int`` function that accepts a ``--min`` and ``--ma
Example OPTION_SPECs
--------------------
Some OPTION_SPEC examples:
Some *OPTION_SPEC* examples:
- ``h/help`` means that both ``-h`` and ``--help`` are valid. The flag is a boolean and can be used more than once. If either flag is used then ``_flag_h`` and ``_flag_help`` will be set to the count of how many times either flag was seen.

8
doc_src/cmds/block.rst
View File

@@ -21,16 +21,16 @@ The block can be removed. Any events which triggered while the block was in plac
Event blocks should not be confused with code blocks, which are created with ``begin``, ``if``, ``while`` or ``for``
The following parameters are available:
The following options are available:
**-l** or **--local**
Release the block automatically at the end of the current innermost code block scope
Release the block automatically at the end of the current innermost code block scope.
**-g** or **--global**
Never automatically release the lock
Never automatically release the lock.
**-e** or **--erase**
Release global block
Release global block.
Example
-------

9
doc_src/cmds/builtin.rst
View File

@@ -16,12 +16,13 @@ Description
``builtin`` forces the shell to use a builtin command, rather than a function or program.
The following parameters are available:
The following options are available:
**-n** or **--names**
List the names of all defined builtins
**-q** or **--query**
Tests if any of the specified builtin(s) exist
Lists the names of all defined builtins.
**-q** or **--query** *BUILTIN*
Tests if any of the specified builtins exist.
Example
-------

50
doc_src/cmds/complete.rst
View File

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

3
doc_src/cmds/contains.rst
View File

@@ -18,7 +18,8 @@ If so, ``contains`` exits with code 0; if not, it exits with code 1.
The following options are available:
- **-i** or **--index** print the word index
**-i** or **--index**
Print the index (number of the element in the set) of the first matching element.
Note that ``contains`` interprets all arguments starting with a **-** as an option to ``contains``, until an **--** argument is reached.

5
doc_src/cmds/dirs.rst
View File

@@ -15,7 +15,10 @@ Description
``dirs`` prints the current :ref:`directory stack <directory-stack>`, as created by :ref:`pushd <cmd-pushd>` and modified by :ref:`popd <cmd-popd>`.
With "-c", it clears the directory stack instead.
The following options are available:
**-c**:
Clear the directory stack instead of printing it.
``dirs`` does not accept any parameters.

12
doc_src/cmds/echo.rst
View File

@@ -17,13 +17,17 @@ Description
The following options are available:
- ``-n``, Do not output a newline
- **-n**
Do not output a newline.
- ``-s``, Do not separate arguments with spaces
**-s**
Do not separate arguments with spaces.
- ``-E``, Disable interpretation of backslash escapes (default)
**-E**
Disable interpretation of backslash escapes (default).
- ``-e``, Enable interpretation of backslash escapes
**-e**
Enable interpretation of backslash escapes.
Unlike other shells, this echo accepts ``--`` to signal the end of the options.

31
doc_src/cmds/fish_add_path.rst
View File

@@ -31,14 +31,29 @@ If a component is not an existing directory, ``fish_add_path`` ignores it.
Options
-------
- ``-a`` or ``--append`` causes the components to be added to the *end* of the variable
- ``-p`` or ``--prepend`` causes the components to be added to the *front* of the variable (this is the default)
- ``-g`` or ``--global`` means to use a global $fish_user_paths
- ``-U`` or ``--universal`` means to use a universal $fish_user_paths - this is the default if it doesn't already exist
- ``-P`` or ``--path`` means to use $PATH directly
- ``-m`` or ``--move`` means to move already existing components to the place they would be added - by default they would be left in place and not added again
- ``-v`` or ``--verbose`` means to print the :ref:`set <cmd-set>` command used
- ``-n`` or ``--dry-run`` means to print the ``set`` command that would be used without executing it
**-a** or **--append**
Add components to the *end* of the variable.
**-p** or **--prepend**
Add components to the *front* of the variable (this is the default).
**-g** or **--global**
Use a global :envvar:`fish_user_paths`.
**-U** or **--universal**
Use a universal :envvar:`fish_user_paths` - this is the default if it doesn't already exist.
**-P** or **--path**
Manipulate :envvar:`PATH` directly.
**-m** or **--move**
Move already-existing components to the place they would be added - by default they would be left in place and not added again.
**-v** or **--verbose**
Print the :ref:`set <cmd-set>` command used.
**-n** or **--dry-run**
Print the ``set`` command that would be used without executing it.
If ``--move`` is used, it may of course lead to the path swapping order, so you should be careful doing that in config.fish.

27
doc_src/cmds/fish_indent.rst
View File

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

12
doc_src/cmds/fish_key_reader.rst
View File

@@ -19,13 +19,17 @@ If the character sequence matches a special key name (see ``bind --key-names``),
The following options are available:
- ``-c`` or ``--continuous`` begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.
**-c** or **--continuous**
Begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.
- ``-V`` or ``--verbose`` tells fish_key_reader to output timing information and explain the sequence in more detail.
**-V** or **--verbose**
Tells fish_key_reader to output timing information and explain the sequence in more detail.
- ``-h`` or ``--help`` prints usage information.
**-h** or **--help**
Displays help about using this command.
- ``-v`` or ``--version`` prints fish_key_reader's version and exits.
**-v** or **--version**
Displays the current :program:`fish` version and then exits.
Usage Notes
-----------

21
doc_src/cmds/fish_opt.rst
View File

@@ -18,19 +18,26 @@ This command provides a way to produce option specifications suitable for use wi
The following ``argparse`` options are available:
- ``-s`` or ``--short`` takes a single letter that is used as the short flag in the option being defined. This option is mandatory.
**-s** or **--short**
Takes a single letter that is used as the short flag in the option being defined. This option is mandatory.
- ``-l`` or ``--long`` takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option spec.
**-l** or **--long**
Takes a string that is used as the long flag in the option being defined. This option is optional and has no default. If no long flag is defined then only the short flag will be allowed when parsing arguments using the option specification.
- ``--long-only`` means the option spec being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., ``--short`` must be specified) but it cannot be used when parsing args using this option spec.
**--long-only**
The option being defined will only allow the long flag name to be used. The short flag name must still be defined (i.e., **--short** must be specified) but it cannot be used when parsing arguments using this option specification.
- ``-o`` or ``--optional-val`` means the option being defined can take a value but it is optional rather than required. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will zero elements if no value was given with the option else it will have exactly one element.
**-o** or **--optional-val**
Tthe option being defined can take a value, but it is optional rather than required. If the option is seen more than once when parsing arguments, only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will zero elements if no value was given with the option else it will have exactly one element.
- ``-r`` or ``--required-val`` means the option being defined requires a value. If the option is seen more than once when parsing arguments only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will have exactly one element.
**-r** or **--required-val**
The option being defined requires a value. If the option is seen more than once when parsing arguments, only the last value seen is saved. This means the resulting flag variable created by ``argparse`` will have exactly one element.
- ``--multiple-vals`` means the option being defined requires a value each time it is seen. Each instance is stored. This means the resulting flag variable created by ``argparse`` will have one element for each instance of this option in the args.
**--multiple-vals**
The option being defined requires a value each time it is seen. Each instance is stored. This means the resulting flag variable created by ``argparse`` will have one element for each instance of this option in the arguments.
- ``-h`` or ``--help`` displays help about using this command.
**-h** or **--help**
Displays help about using this command.
Examples
--------

9
doc_src/cmds/funced.rst
View File

@@ -21,11 +21,14 @@ If the ``$VISUAL`` environment variable is set, it will be used as the program t
If there is no function called *NAME*, a new function will be created with the specified name.
- ``-e command`` or ``--editor command`` Open the function body inside the text editor given by the command (for example, ``-e vi``). The special command ``fish`` will use the built-in editor (same as specifying ``-i``).
**-e command** or **--editor command**
Open the function body inside the text editor given by the command (for example, **-e vi**). The special command ``fish`` will use the built-in editor (same as specifying **-i**).
- ``-i`` or ``--interactive`` Force opening the function body in the built-in editor even if ``$VISUAL`` or ``$EDITOR`` is defined.
**-i** or **--interactive**
Force opening the function body in the built-in editor even if ``$VISUAL`` or ``$EDITOR`` is defined.
- ``-s`` or ``--save`` Automatically save the function after successfully editing it.
**-s** or **--save**
Automatically save the function after successfully editing it.
Example
-------

36
doc_src/cmds/function.rst
View File

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

37
doc_src/cmds/functions.rst
View File

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

45
doc_src/cmds/history.rst
View File

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

17
doc_src/cmds/jobs.rst
View File

@@ -16,17 +16,22 @@ Description
``jobs`` prints a list of the currently running :ref:`jobs <syntax-job-control>` and their status.
jobs accepts the following switches:
``jobs`` accepts the following options:
- ``-c`` or ``--command`` prints the command name for each process in jobs.
**-c** or **--command**
Prints the command name for each process in jobs.
- ``-g`` or ``--group`` only prints the group ID of each job.
**-g** or **--group**
Only prints the group ID of each job.
- ``-l`` or ``--last`` prints only the last job to be started.
**-l** or **--last**
Prints only the last job to be started.
- ``-p`` or ``--pid`` prints the process ID for each process in all jobs.
**-p** or **--pid**
Prints the process ID for each process in all jobs.
- ``-q`` or ``--query`` prints no output for evaluation of jobs by exit status only. For compatibility with old fish versions this is also ``--quiet`` (but this is deprecated).
**-q** or **--query**
Prints no output for evaluation of jobs by exit status only. For compatibility with old fish versions this is also **--quiet** (but this is deprecated).
On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%.

11
doc_src/cmds/prompt_pwd.rst
View File

@@ -24,9 +24,14 @@ If any positional arguments are given, prompt_pwd shortens them instead of $PWD.
Options
-------
- ``-h`` or ``--help`` displays the help and exits
- ``-d`` or ``--dir-length=MAX`` causes the components to be shortened to MAX characters each. This overrides $fish_prompt_pwd_dir_length.
- ``-D`` or ``--full-length-dirs=NUM`` keeps NUM components (counted from the right) as full length without shortening. This overrides $fish_prompt_pwd_full_dirs.
**-d** or **--dir-length** *MAX*
Causes the components to be shortened to *MAX* characters each. This overrides :envvar:`fish_prompt_pwd_dir_length`.
**-D** or **--full-length-dirs** *NUM*
Keeps *NUM* components (counted from the right) as full length without shortening. This overrides :envvar:`fish_prompt_pwd_full_dirs`.
**-h** or **--help**
Displays help about using this command.
Examples
--------

9
doc_src/cmds/psub.rst
View File

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

6
doc_src/cmds/pwd.rst
View File

@@ -25,9 +25,11 @@ Description
The following options are available:
- ``-L`` or ``--logical`` Output the logical working directory, without resolving symlinks (default behavior).
**-L** or **--logical**
Output the logical working directory, without resolving symlinks (default behavior).
- ``-P`` or ``--physical`` Output the physical working directory, with symlinks resolved.
**-P** or **--physical**
Output the physical working directory, with symlinks resolved.
See Also
--------

3
doc_src/cmds/realpath.rst
View File

@@ -27,4 +27,5 @@ If a :command:`realpath` command exists, that will be preferred.
The following options are available:
- ``-s`` or ``--no-symlinks``: Don't resolve symlinks, only make paths absolute, squash multiple slashes and remove trailing slashes.
**-s** or **--no-symlinks**
Don't resolve symlinks, only make paths absolute, squash multiple slashes and remove trailing slashes.

46
doc_src/cmds/set.rst
View File

@@ -33,40 +33,54 @@ With ``--show``, ``set`` will describe the given variable names, explaining how
The following options control variable scope:
- ``-f`` or ``--function`` scopes the variable to the currently executing function. It is erased when the function ends.
**-f** or **--function**
Scopes the variable to the currently executing function. It is erased when the function ends.
- ``-l`` or ``--local`` scopes the variable to the currently executing block. It is erased when the block ends. Outside of a block, this is the same as ``--function``.
**-l** or **--local**
Scopes the variable to the currently executing block. It is erased when the block ends. Outside of a block, this is the same as **--function**.
- ``-g`` or ``--global`` causes the specified shell variable to be given a global scope. Global variables don't disappear and are available to all functions running in the same shell. They can even be modified.
**-g** or **--global**
Causes the specified shell variable to be given a global scope. Global variables don't disappear and are available to all functions running in the same shell. They can even be modified.
- ``-U`` or ``--universal`` causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current user's fish instances on the current computer, and will be preserved across restarts of the shell.
**-U** or **--universal**
Causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current user's fish instances on the current computer, and will be preserved across restarts of the shell.
These options control additional variable options:
- ``-x`` or ``--export`` causes the specified shell variable to be exported to child processes (making it an "environment variable")
**-x** or **--export**
Causes the specified shell variable to be exported to child processes (making it an "environment variable")
- ``-u`` or ``--unexport`` causes the specified shell variable to NOT be exported to child processes
**-u** or **--unexport**
Causes the specified shell variable to NOT be exported to child processes
- ``--path`` causes the specified variable to be treated as a path variable, meaning it will automatically be split on colons, and joined using colons when quoted (``echo "$PATH"``) or exported.
**--path**
Causes the specified variable to be treated as a :ref:`path variable <variables-path>`, meaning it will automatically be split on colons, and joined using colons when quoted (``echo "$PATH"``) or exported.
- ``--unpath`` causes the specified variable to not be treated as a path variable. Variables with a name ending in "PATH" are automatically path variables, so this can be used to treat such a variable normally.
**--unpath**
Causes the specified variable to not be treated as a :ref:`path variable <variables-path>`. Variables with a name ending in "PATH" are automatically path variables, so this can be used to treat such a variable normally.
The following other options are available:
- ``-a`` or ``--append`` causes the values to be appended to the current set of values for the variable. This can be used with ``--prepend`` to both append and prepend at the same time. This cannot be used when assigning to a variable slice.
**-a** or **--append**
Causes the values to be appended to the current set of values for the variable. This can be used with **--prepend** to both append and prepend at the same time. This cannot be used when assigning to a variable slice.
- ``-p`` or ``--prepend`` causes the values to be prepended to the current set of values for the variable. This can be used with ``--append`` to both append and prepend at the same time. This cannot be used when assigning to a variable slice.
**-p** or **--prepend**
Causes the values to be prepended to the current set of values for the variable. This can be used with **--append** to both append and prepend at the same time. This cannot be used when assigning to a variable slice.
- ``-e`` or ``--erase`` causes the specified shell variables to be erased
**-e** or **--erase**
Causes the specified shell variables to be erased
- ``-q`` or ``--query`` test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined, up to a maximum of 255. If no variable was given, it also returns 255.
**-q** or **--query**
Test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined, up to a maximum of 255. If no variable was given, it also returns 255.
- ``-n`` or ``--names``: List only the names of all defined variables, not their value. The names are guaranteed to be sorted.
**-n** or **--names**
List only the names of all defined variables, not their value. The names are guaranteed to be sorted.
- ``-S`` or ``--show`` shows information about the given variables. If no variable names are given then all variables are shown in sorted order. It shows the scopes the given variables are set in, along with the values in each and whether or not it is exported. No other flags can be used with this option.
- ``-L`` or ``--long`` do not abbreviate long values when printing set variables
**-S** or **--show**
Shows information about the given variables. If no variable names are given then all variables are shown in sorted order. It shows the scopes the given variables are set in, along with the values in each and whether or not it is exported. No other flags can be used with this option.
**-L** or **--long**
Do not abbreviate long values when printing set variables.
If a variable is set to more than one value, the variable will be a list with the specified elements. If a variable is set to zero elements, it will become a list with zero elements.

31
doc_src/cmds/set_color.rst
View File

@@ -26,17 +26,30 @@ An RGB value with three or six hex digits, such as A0FF33 or f2f can be used. ``
A second color may be given as a desired fallback color. e.g. ``set_color 124212 brblue`` will instruct set_color to use *brblue* if a terminal is not capable of the exact shade of grey desired. This is very useful when an 8 or 16 color terminal might otherwise not use a color.
The following *OPTIONS* are available:
The following options are available:
- ``-b``, ``--background`` *COLOR* sets the background color.
- ``-c``, ``--print-colors`` prints a list of the 16 named colors.
- ``-o``, ``--bold`` sets bold mode.
- ``-d``, ``--dim`` sets dim mode.
- ``-i``, ``--italics`` sets italics mode.
- ``-r``, ``--reverse`` sets reverse mode.
- ``-u``, ``--underline`` sets underlined mode.
**-b** or **--background** *COLOR*
Sets the background color.
Using the *normal* keyword will reset foreground, background, and all formatting back to default.
**-c** or **--print-colors**
Prints a list of the 16 named colors.
**-o** or **--bold**
Sets bold mode.
**-d** or **--dim**
Sets dim mode.
**-i** or **--italics**
Sets italics mode.
**-r** or **--reverse**
Sets reverse mode.
**-u** or **--underline**
Sets underlined mode.
Using the **normal** keyword will reset foreground, background, and all formatting back to default.
Notes
-----

58
doc_src/cmds/status.rst
View File

@@ -36,44 +36,62 @@ With no arguments, ``status`` displays a summary of the current login and job co
The following operations (sub-commands) are available:
- ``is-command-substitution`` returns 0 if fish is currently executing a command substitution. Also ``-c`` or ``--is-command-substitution``.
**is-command-substitution**, **-c** or **--is-command-substitution**
Returns 0 if fish is currently executing a command substitution.
- ``is-block`` returns 0 if fish is currently executing a block of code. Also ``-b`` or ``--is-block``.
**is-block**, **-b** or **--is-block**
Returns 0 if fish is currently executing a block of code.
- ``is-breakpoint`` returns 0 if fish is currently showing a prompt in the context of a ``breakpoint`` command. See also the ``fish_breakpoint_prompt`` function.
**is-breakpoint**
Returns 0 if fish is currently showing a prompt in the context of a :ref:`breakpoint <cmd-breakpoint>` command. See also the :ref:`fish_breakpoint_prompt <cmd-fish_breakpoint_prompt>` function.
- ``is-interactive`` returns 0 if fish is interactive - that is, connected to a keyboard. Also ``-i`` or ``--is-interactive``.
**is-interactive**, **-i** or **--is-interactive**
Returns 0 if fish is interactive - that is, connected to a keyboard.
- ``is-login`` returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH. Also ``-l`` or ``--is-login``.
**is-login**, **-l** or **--is-login**
Returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up :envvar:`PATH`.
- ``is-full-job-control`` returns 0 if full job control is enabled. Also ``--is-full-job-control`` (no short flag).
**is-full-job-control** or **--is-full-job-control**
Returns 0 if full job control is enabled.
- ``is-interactive-job-control`` returns 0 if interactive job control is enabled. Also, ``--is-interactive-job-control`` (no short flag).
**is-interactive-job-control** or **--is-interactive-job-control**
Returns 0 if interactive job control is enabled.
- ``is-no-job-control`` returns 0 if no job control is enabled. Also ``--is-no-job-control`` (no short flag).
**is-no-job-control** or **--is-no-job-control**
Returns 0 if no job control is enabled.
- ``current-command`` prints the name of the currently-running function or command, like the deprecated ``_`` variable.
**current-command**
Prints the name of the currently-running function or command, like the deprecated :envvar:`_` variable.
- ``filename`` prints the filename of the currently-running script. Also ``current-filename``, ``-f`` or ``--current-filename``. If the current script was called via a symlink, this will return the symlink. If the current script was received by piping into ``source``, then this will return ``-``.
**filename**, **current-filename**, **-f** or **--current-filename**
Prints the filename of the currently-running script. If the current script was called via a symlink, this will return the symlink. If the current script was received by piping into :ref:`source <cmd-source>`, then this will return ``-``.
- ``basename`` prints just the filename of the running script, without any path-components before.
**basename**
Prints just the filename of the running script, without any path components before.
- ``dirname`` prints just the path to the running script, without the actual filename itself. This can be relative to $PWD (including just "."), depending on how the script was called. This is the same as passing the ``filename`` to ``dirname(3)``. It's useful if you want to use other files in the current script's directory or similar.
**dirname**
Prints just the path to the running script, without the actual filename itself. This can be relative to :envvar:`PWD` (including just "."), depending on how the script was called. This is the same as passing the filename to ``dirname(3)``. It's useful if you want to use other files in the current script's directory or similar.
- ``fish-path`` prints the absolute path to the currently executing instance of fish.
**fish-path**
Prints the absolute path to the currently executing instance of fish.
- ``function`` prints the name of the currently called function if able, when missing displays "Not a
function" (or equivalent translated string). Also ``current-function``.
**function** or **current-function**
Prints the name of the currently called function if able, when missing displays "Not a function" (or equivalent translated string).
- ``line-number`` prints the line number of the currently running script. Also ``current-line-number``, ``-n`` or ``--current-line-number``.
**line-number**, **current-line-number**, **-n** or **--current-line-number**
Prints the line number of the currently running script.
- ``stack-trace`` prints a stack trace of all function calls on the call stack. Also ``print-stack-trace``, ``-t`` or ``--print-stack-trace``.
**stack-trace**, **print-stack-trace**, **-t** or **--print-stack-trace**
Prints a stack trace of all function calls on the call stack.
- ``job-control CONTROL_TYPE`` sets the job control type, which can be ``none``, ``full``, or ``interactive``. Also ``-j CONTROL_TYPE`` or ``--job-control CONTROL_TYPE``.
**job-control**, **-j** or **--job-control** *CONTROL_TYPE*
Sets the job control type to *CONTROL_TYPE*, which can be **none**, **full**, or **interactive**.
- ``features`` lists all available feature flags.
**features**
Lists all available feature flags.
- ``test-feature FEATURE`` returns 0 when FEATURE is enabled, 1 if it is disabled, and 2 if it is not recognized.
**test-feature** *FEATURE*
Returns 0 when FEATURE is enabled, 1 if it is disabled, and 2 if it is not recognized.
Notes
-----

98
doc_src/cmds/test.rst
View File

@@ -32,84 +32,116 @@ When using a variable as an argument for a test operator you should almost alway
Operators for files and directories
-----------------------------------
- ``-b FILE`` returns true if ``FILE`` is a block device.
**-b** *FILE*
Returns true if *FILE* is a block device.
- ``-c FILE`` returns true if ``FILE`` is a character device.
**-c** *FILE*
Returns true if *FILE* is a character device.
- ``-d FILE`` returns true if ``FILE`` is a directory.
**-d** *FILE*
Returns true if *FILE* is a directory.
- ``-e FILE`` returns true if ``FILE`` exists.
**-e** *FILE*
Returns true if *FILE* exists.
- ``-f FILE`` returns true if ``FILE`` is a regular file.
**-f** *FILE*
Returns true if *FILE* is a regular file.
- ``-g FILE`` returns true if ``FILE`` has the set-group-ID bit set.
**-g** *FILE*
Returns true if *FILE* has the set-group-ID bit set.
- ``-G FILE`` returns true if ``FILE`` exists and has the same group ID as the current user.
**-G** *FILE*
Returns true if *FILE* exists and has the same group ID as the current user.
- ``-k FILE`` returns true if ``FILE`` has the sticky bit set. If the OS does not support the concept it returns false. See https://en.wikipedia.org/wiki/Sticky_bit.
**-k** *FILE*
Returns true if *FILE* has the sticky bit set. If the OS does not support the concept it returns false. See https://en.wikipedia.org/wiki/Sticky_bit.
- ``-L FILE`` returns true if ``FILE`` is a symbolic link.
**-L** *FILE*
Returns true if *FILE* is a symbolic link.
- ``-O FILE`` returns true if ``FILE`` exists and is owned by the current user.
**-O** *FILE*
Returns true if *FILE* exists and is owned by the current user.
- ``-p FILE`` returns true if ``FILE`` is a named pipe.
**-p** *FILE*
Returns true if *FILE* is a named pipe.
- ``-r FILE`` returns true if ``FILE`` is marked as readable.
**-r** *FILE*
Returns true if *FILE* is marked as readable.
- ``-s FILE`` returns true if the size of ``FILE`` is greater than zero.
**-s** *FILE*
Returns true if the size of *FILE* is greater than zero.
- ``-S FILE`` returns true if ``FILE`` is a socket.
**-S** *FILE*
Returns true if *FILE* is a socket.
- ``-t FD`` returns true if the file descriptor ``FD`` is a terminal (TTY).
**-t** *FD*
Returns true if the file descriptor *FD* is a terminal (TTY).
- ``-u FILE`` returns true if ``FILE`` has the set-user-ID bit set.
**-u** *FILE*
Returns true if *FILE* has the set-user-ID bit set.
- ``-w FILE`` returns true if ``FILE`` is marked as writable; note that this does not check if the filesystem is read-only.
**-w** *FILE*
Returns true if *FILE* is marked as writable; note that this does not check if the filesystem is read-only.
- ``-x FILE`` returns true if ``FILE`` is marked as executable.
**-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.
*STRING1* **=** *STRING2*
Returns true if the strings *STRING1* and *STRING2* are identical.
- ``STRING1 != STRING2`` returns true if the strings ``STRING1`` and ``STRING2`` are not identical.
*STRING1* **!=** *STRING2*
Returns true if the strings *STRING1* and *STRING2* are not identical.
- ``-n STRING`` returns true if the length of ``STRING`` is non-zero.
**-n** *STRING*
Returns true if the length of *STRING* is non-zero.
- ``-z STRING`` returns true if the length of ``STRING`` is zero.
**-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.
*NUM1* **-eq** *NUM2*
Returns true if *NUM1* and *NUM2* are numerically equal.
- ``NUM1 -ne NUM2`` returns true if ``NUM1`` and ``NUM2`` are not numerically equal.
*NUM1* **-ne** *NUM2*
Returns true if *NUM1* and *NUM2* are not numerically equal.
- ``NUM1 -gt NUM2`` returns true if ``NUM1`` is greater than ``NUM2``.
*NUM1* **-gt** *NUM2*
Returns true if *NUM1* is greater than *NUM2*.
- ``NUM1 -ge NUM2`` returns true if ``NUM1`` is greater than or equal to ``NUM2``.
*NUM1* **-ge** *NUM2*
Returns true if *NUM1* is greater than or equal to *NUM2*.
- ``NUM1 -lt NUM2`` returns true if ``NUM1`` is less than ``NUM2``.
*NUM1* **-lt** *NUM2*
Returns true if *NUM1* is less than *NUM2*.
- ``NUM1 -le NUM2`` returns true if ``NUM1`` is less than or equal to ``NUM2``.
*NUM1* **-le** *NUM2*
Returns true if *NUM1* is less than or equal to *NUM2*.
Both integers and floating point numbers are supported.
Operators to combine expressions
--------------------------------
- ``COND1 -a COND2`` returns true if both ``COND1`` and ``COND2`` are true.
*COND1* **-a** *COND2*
Returns true if both *COND1* and *COND2* are true.
- ``COND1 -o COND2`` returns true if either ``COND1`` or ``COND2`` are true.
*COND1* **-o** *COND2*
Returns true if either *COND1* or *COND2* are true.
Expressions can be inverted using the ``!`` operator:
Expressions can be inverted using the **!** operator:
- ``! EXPRESSION`` returns true if ``EXPRESSION`` is false, and false if ``EXPRESSION`` is true.
**!** *EXPRESSION*
Returns true if *EXPRESSION* is false, and false if *EXPRESSION* is true.
Expressions can be grouped using parentheses.
- ``( EXPRESSION )`` returns the value of ``EXPRESSION``.
**(** *EXPRESSION* **)**
Returns the value of *EXPRESSION*.
Note that parentheses will usually require escaping with ``\(`` to avoid being interpreted as a command substitution.

12
doc_src/cmds/trap.rst
View File

@@ -17,13 +17,17 @@ Description
The following parameters are available:
- ``ARG`` is the command to be executed on signal delivery.
*ARG*
Command to be executed on signal delivery.
- ``REASON`` is the name of the event to trap. For example, a signal like ``INT`` or ``SIGINT``, or the special symbol ``EXIT``.
*REASON*
Name of the event to trap. For example, a signal like ``INT`` or ``SIGINT``, or the special symbol ``EXIT``.
- ``-l`` or ``--list-signals`` prints a list of signal names.
**-l** or **--list-signals**
Prints a list of signal names.
- ``-p`` or ``--print`` prints all defined signal handlers.
**-p** or **--print**
Prints all defined signal handlers.
If ``ARG`` and ``REASON`` are both specified, ``ARG`` is the command to be executed when the event specified by ``REASON`` occurs (e.g., the signal is delivered).

21
doc_src/cmds/type.rst
View File

@@ -17,19 +17,26 @@ With no options, :command:`type` indicates how each ``NAME`` would be interprete
The following options are available:
- ``-a`` or ``--all`` prints all of possible definitions of the specified names.
**-a** or **--all**
Prints all of possible definitions of the specified names.
- ``-s`` or ``--short`` suppresses function expansion when used with no options or with ``-a``/``--all``.
**-s** or **--short**
Suppresses function expansion when used with no options or with **-a**/**--all**.
- ``-f`` or ``--no-functions`` suppresses function and builtin lookup.
**-f** or **--no-functions**
Suppresses function and builtin lookup.
- ``-t`` or ``--type`` prints ``function``, ``builtin``, or ``file`` if ``NAME`` is a shell function, builtin, or disk file, respectively.
**-t** or **--type**
Prints ``function``, ``builtin``, or ``file`` if *NAME* is a shell function, builtin, or disk file, respectively.
- ``-p`` or ``--path`` prints the path to ``NAME`` if ``NAME`` resolves to an executable file in :envvar:`PATH`, the path to the script containing the definition of the function ``NAME`` if ``NAME`` resolves to a function loaded from a file on disk (i.e. not interactively defined at the prompt), or nothing otherwise.
**-p** or **--path**
Prints the path to *NAME* if *NAME* resolves to an executable file in :envvar:`PATH`, the path to the script containing the definition of the function *NAME* if *NAME* resolves to a function loaded from a file on disk (i.e. not interactively defined at the prompt), or nothing otherwise.
- ``-P`` or ``--force-path`` returns the path to the executable file ``NAME``, presuming ``NAME`` is found in the :envvar:`PATH` environment variable, or nothing otherwise. ``--force-path`` explicitly resolves only the path to executable files in :envvar:`PATH`, regardless of whether ``$NAME`` is shadowed by a function or builtin with the same name.
**-P** or **--force-path**
Returns the path to the executable file *NAME*, presuming *NAME* is found in the :envvar:`PATH` environment variable, or nothing otherwise. **--force-path** explicitly resolves only the path to executable files in :envvar:`PATH`, regardless of whether *NAME* is shadowed by a function or builtin with the same name.
- ``-q`` or ``--query`` suppresses all output; this is useful when testing the exit status. For compatibility with old fish versions this is also ``--quiet``.
**-q** or **--query**
Suppresses all output; this is useful when testing the exit status. For compatibility with old fish versions this is also **--quiet**.
The ``-q``, ``-p``, ``-t`` and ``-P`` flags (and their long flag aliases) are mutually exclusive. Only one can be specified at a time.

43
doc_src/cmds/ulimit.rst
View File

@@ -18,43 +18,56 @@ Description
Use one of the following switches to specify which resource limit to set or report:
- ``-c`` or ``--core-size``: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled.
**-c** or **--core-size**
The maximum size of core files created. By setting this limit to zero, core dumps can be disabled.
- ``-d`` or ``--data-size``: the maximum size of a process' data segment.
**-d** or **--data-size**
The maximum size of a process' data segment.
- ``-f`` or ``--file-size``: the maximum size of files created by the shell.
**-f** or **--file-size**
The maximum size of files created by the shell.
- ``-l`` or ``--lock-size``: the maximum size that may be locked into memory.
**-l** or **--lock-size**
The maximum size that may be locked into memory.
- ``-m`` or ``--resident-set-size``: the maximum resident set size.
**-m** or **--resident-set-size**
The maximum resident set size.
- ``-n`` or ``--file-descriptor-count``: the maximum number of open file descriptors (most systems do not allow this value to be set).
**-n** or **--file-descriptor-count**
The maximum number of open file descriptors (most systems do not allow this value to be set).
- ``-s`` or ``--stack-size``: the maximum stack size.
**-s** or **--stack-size**
The maximum stack size.
- ``-t`` or ``--cpu-time``: the maximum amount of CPU time in seconds.
**-t** or **--cpu-time**
The maximum amount of CPU time in seconds.
- ``-u`` or ``--process-count``: the maximum number of processes available to a single user.
**-u** or **--process-count**
The maximum number of processes available to a single user.
- ``-v`` or ``--virtual-memory-size`` The maximum amount of virtual memory available to the shell.
**-v** or **--virtual-memory-size**
The maximum amount of virtual memory available to the shell.
Note that not all these limits are available in all operating systems.
The value of limit can be a number in the unit specified for the resource or one of the special values ``hard``, ``soft``, or ``unlimited``, which stand for the current hard limit, the current soft limit, and no limit, respectively.
If limit is given, it is the new value of the specified resource. If no option is given, then ``-f`` is assumed. Values are in kilobytes, except for ``-t``, which is in seconds and ``-n`` and ``-u``, which are unscaled values. The exit status is 0 unless an invalid option or argument is supplied, or an error occurs while setting a new limit.
If limit is given, it is the new value of the specified resource. If no option is given, then **-f** is assumed. Values are in kilobytes, except for **-t**, which is in seconds and **-n** and **-u**, which are unscaled values. The exit status is 0 unless an invalid option or argument is supplied, or an error occurs while setting a new limit.
``ulimit`` also accepts the following switches that determine what type of limit to set:
- ``-H`` or ``--hard`` sets hard resource limit
**-H** or **--hard**
Sets hard resource limit.
- ``-S`` or ``--soft`` sets soft resource limit
**-S** or **--soft**
Sets soft resource limit.
A hard limit can only be decreased. Once it is set it cannot be increased; a soft limit may be increased up to the value of the hard limit. If neither ``-H`` nor ``-S`` is specified, both the soft and hard limits are updated when assigning a new limit value, and the soft limit is used when reporting the current value.
A hard limit can only be decreased. Once it is set it cannot be increased; a soft limit may be increased up to the value of the hard limit. If neither **-H** nor **-S** is specified, both the soft and hard limits are updated when assigning a new limit value, and the soft limit is used when reporting the current value.
The following additional options are also understood by ``ulimit``:
- ``-a`` or ``--all`` prints all current limits
**-a** or **--all**
Prints all current limits.
The ``fish`` implementation of ``ulimit`` should behave identically to the implementation in bash, except for these differences:

9
doc_src/cmds/umask.rst
View File

@@ -22,11 +22,14 @@ Access rights are explained in the manual page for the ``chmod(1)`` program.
With no parameters, the current file creation mode mask is printed as an octal number.
- ``-h`` or ``--help`` prints this message.
**-S** or **--symbolic**
Prints the umask in symbolic form instead of octal form.
- ``-S`` or ``--symbolic`` prints the umask in symbolic form instead of octal form.
**-p** or **--as-command**
Outputs the umask in a form that may be reused as input.
- ``-p`` or ``--as-command`` outputs the umask in a form that may be reused as input
**-h** or **--help**
Displays help about using this command.
If a numeric mask is specified as a parameter, the current shell's umask will be set to that value, and the rights specified by that mask will be removed from new files and directories by default.

11
doc_src/cmds/wait.rst
View File

@@ -15,10 +15,13 @@ Description
``wait`` waits for child jobs to complete.
- If a pid is specified, the command waits for the job that the process with the pid belongs to.
- If a process name is specified, the command waits for the jobs that the matched processes belong to.
- If neither a pid nor a process name is specified, the command waits for all background jobs.
- 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.
If a *PID* is specified, the command waits for the job that the process with that process ID belongs to.
If a *PROCESS_NAME* is specified, the command waits for the jobs that the matched processes belong to.
If neither a pid nor a process name is specified, the command waits for all background jobs.
If the **-n** or **--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
-------